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Production Note 


This book was produced with the VAX DOCUMENT electronic publishing 
system, a software tool developed and sold by DIGITAL. In this system, 
writers use an ASCII text editor to create source files containing text and 
English-like code; this code labels the structural elements of the document, 
such as chapters, paragraphs, and tables. The VAX DOCUMENT software, 
which runs on the VMS operating system, interprets the code to format 
the text, generate a table of contents and index, and paginate the entire 
document. Writers can print the document on the terminal or line printer, 
or they can use DIGITAL-supported devices, such as the LN03 laser 
printer and PostScript printers (PrintServer 40 or LNO3R ScriptPrinter), 
to produce a typeset-quality copy containing integrated graphics. 
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Preface 


Intended Audience 


This document is for experienced programmers who will be creating 
applications with VMS DECwindows. This document assumes a 
knowledge of VAX calling standards and of the C programming language. 





Document Structure 


This document is composed of an Introduction chapter and fourteen 
Reference chapters. 


The Introduction chapter provides information on the documentation 
format for the VMS DECwindows graphics programming routines. 


The Reference chapters provide the following information on each 
programming routine: 


How to call the routine according to the VMS calling standard for any 
VAX supported language. 


How to call the routine according to the MIT C programming 
standards. 


A description of each argument in the routine. 
A description of how the routine functions. 


A list of values returned by the routine. 


This document is in two parts. Part I contains the Introduction chapter 
and the Reference chapters for the following sets of routines: 


Display routines 

Window routines 

Event routines 

Graphics context routines 
Graphics routines 


Text routines 


Part II contains the Reference chapters for the following sets of routines: 


Property routines 
Region routines 
Window and session manager routines 


Pixmap and bitmap routines 
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¢ Color routines 
¢ Font routines 


* Cursor routines 


¢ Resource manager routines 





Associated Documents 


Readers may find the following documents useful when programming with 


DECwindows Xlib routines: 


¢ VMS DECwindows Xlib Programming Volume——Describes how to 
program DECwindows routines using the VAX and MIT C bindings 


¢ VMS DECwindows Guide to Application Programming—-As well 
as offering a guide to programming the DECwindows toolkit, this 
manual provides an overview of programming in the DECwindows 


environment 


e XUI Style Guide—Describes the standard DECwindows user interface 





Conventions 
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The following conventions are used in this manual: 


mouse 


{} 


The term mouse is used to refer to any pointing 
device, such as a mouse, a puck, or a stylus. 


in examples, a horizontal ellipsis indicates one of the 
following possibilities: 


* Additional optional arguments in a statement 
have been omitted. 

* The preceding item or items can be repeated one 
or more times. 

* Additional parameters, values, or other 
information can be entered. 


A vertical ellipsis indicates the omission of items from 
a code example or command format; the items are 
omitted because they are not important to the topic 
being discussed. 


In format descriptions, parentheses indicate that, if 
you choose more than one option, you must enclose 
the choices in parentheses. 


In format descriptions, brackets indicate that whatever 
is enclosed is optional; you can select none, one, or 
all of the choices. 


In format descriptions, braces surround a required 
choice of options; you must choose one of the options 
listed. 


boldface text 


UPPERCASE TEXT 


numbers 
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Boldface text represents the introduction of a new 
term or the name of an argument, an attribute, or a 
reason. 


Uppercase letters indicate the name of a routine, the 
name of a file, the name of a file protection code, or 
the abbreviation for a system privilege. 


Unless otherwise noted, all numbers in the text are 
assumed to be decimal. Nondecimal radixes—binary, 
octal, or hexadecimal—are explicitly indicated. 
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introduction to the DECwindows Xlib Routines 


The VMS DECwindows Xlib programming library routines provide the 
programming interface to the X Window System, Version 11. Many of 
these routines provide input directly to or receive output directly from 
the X server and are therefore the lowest level of programming interface. 
Other sets of VMS DECwindows tools are built on top of these routines to 
provide higher levels of programming interface. 


The VMS DECwindows Xlib library (hereafter referred to as Xlib) is a 
subset of the MIT X Window System Release 2 Xlib with several additions. 


Xlib provides a complete implementation of the Xlib C Language 

X Interface (Release 2) with the exception of the X Window System, 
Version 10 compatibility routines and the X extension routines. The 
following routines and macros are not provided in Xlib: 


X Version 10 compatibility routines: 


XCreateAssocTable 
XDeleteAssoc 
XDestroyAssocTable 
XDraw 
XDrawFilled 
XLookUpAssoc 
XMakeAssocTable 


X Version 11 extension routines/macros: 


Data 

GetReq 
GetReqExtra 
GetResReq 
GetEmptyReq 
LockDisplay 
PackData 
SyncHandle 
UnlockDisplay 
XAddToExtensionList 
XAllocID 

Xcalloc 
XESetCloseDisplay 
XESetCreateFont 
XESetCreateGC 
XESetCopyGC 
XESetError 
XESetErrorString 
XESetEventToWire 
XESetFlushGC 
XESetFreeGC 
XESetFreeFont 
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XESetWireToEvent 
XFindOnExtensionList 
XFlushGC 

Xfree 
XFreeExtensionList 
XInitExtension 
XListExtensions 
Xmalloc 
XQueryExtension 
_XAllocScratch 
_XFlushGCCache 
_xXRead 

_XReply 

_XSend 


Xlib provides several additions to the MIT Xlib, including support for 
asynchronous programming and entry points that conform to the VAX 
Procedure Calling Standard. You can perform Xlib calls at Asynchronous 
System Trap (AST) level, and these can be mixed with other calls at non- 
AST level. Xlib also extends the LOOKUP STRING routine to support 
DIGITAL international keyboards and the ISO Latin 1 character set. 


The routines are organized according to function. Within each functional 
group, they are organized alphabetically. The categories of Xlib routines 
are as follows: 


e 


Display routines connect and disconnect the server, send and retrieve 
data to and from the server, and obtain default information about the 
display with which you are working. 


Window routines create, map, move, change, and destroy windows. 
This category also includes routines that obtain information about a 
window. 


Event and error handling routines select and check input/output 
events and handle error conditions. 


Graphics context routines create, change, and delete graphics context 
structures and attributes. 


Graphics routines draw, fill, and erase points, lines, polygons, and arcs. 
This category also includes routines that handle complex images. 


Text routines manipulate text in a window. 


Property routines create, use, and destroy window properties. This 
category also includes context routines. 


Region routines create, use, and destroy regions within a window. 


Window and session management routines, which are special purpose 
routines normally only used by the window manager and session 
manager. 


Pixmap and bitmap routines create and free pixmaps and bitmaps. 


Color routines manipulate color maps and allocate, define, and use 
colors. This category also includes visual information routines. 
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e Font routines specify, load, and free fonts. 

¢ Cursor routines create, use, and delete cursors. 

e Resource manager routines store, retrieve, and search for resources. 
For each functional group of routines, an overview section at the beginning 
of each chapter describes the routines in general. The overview section 


also includes descriptions of each predefined data structure used within 
that functional group. 


Most routines can be formatted and called according to the following 
bindings: 


¢ VAX binding—Where the routine follows the VAX Procedure Calling 
Standard 


* C binding—Where the routine follows the MIT C language binding 


Xlib can be used by programs written in any language that follows the 
VAX Procedure Calling Standard. Xlib library definition files are provided 
for the following 8 languages and may be found in SYS$LIBRARY: 


e VAX Ada 


* VAX BASIC 
* VAX BLISS 
° VAX C 


¢ VAX FORTRAN 
¢ VAX MACRO 

¢ VAX Pascal 

e VAX PL/I 


Xlib programs that desire to retain binary compatibility with future 
releases of DECwindows should not be coded to use the MIT C language 
macros. Instead they should use the corresponding routine calls. No 
commitment is made to retain binary compatibility for programs that use 
the macro interface. 


Xlib should not be used by VAX C language programs that have been 
compiled with the /G_FLOAT qualifier. Xlib has been compiled with the 
default /D_FLOAT qualifier and should not be intermixed with VAX C 
/G_FLOAT modules. 


If your program is going to use other portions of code written in another 
VAX language, use the VAX binding to ensure that the VAX Procedure 
Calling Standard is met. If the programming language you are using 
cannot easily support the style used in many of the MIT C binding routines 
(such as parameters passed by value and structure types used), you might 
want to use the VAX binding. If the programming language you are using 
easily accommodates the MIT C language binding (for example, C and 
perhaps VAX BLISS), use the MIT C binding. 
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1.1 


1.1.1 


1.1.3 
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Routine Documentation Format 


Routine Name 


Overview 


VAX Format 
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Each Xlib routine is documented for both bindings using a standard 
template. This section describes each category in this template, the 
information that is presented under each category, and the format used to 
present the information. 


The following subsections describe each part in the documentation format. 


The generic name of the routine that is used to refer to the routine for 
both the VAX or C bindings. 


A statement describing what the routine does. The overview is relevant to 
both the VAX and C bindings. 


The VAX routine call format. The format syntax is summarized in 
Table 1-1. 


Table 1-1 General Rules of Syntax 


Element Syntax Rule 

Routine entry point name The name is shown in all capital letters with the prefix 
X. The routine entry point name is required. 

Equals sign For specific return values, the equals sign is required. 

Parentheses Open and close parentheses surround the argument 


list in a routine call. They are required. 


Argument names Argument names, including names of return 
arguments, are always shown in lowercase 
characters. All arguments not enclosed by brackets 
([]) are required. They must be listed in the same 
order in your program as they appear in the format. 


Spaces One or more spaces are shown between the entry 
point name and the first argument, and between each 
argument. They are not required. 


Brackets Brackets ([]) surround optional arguments. Commas 
that appear inside brackets are optional and appear 
only when the optional argument appears. The 
brackets are not required. 


Commas Commas must appear between required arguments. 
When commas appear inside brackets ([]), they 
appear only when the optional argument appears. 


The VAX format is followed by a table that lists information about each 
argument listed in the format. Arguments are described in the order they 
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appear in the format. The table lists the argument name, usage, data 
type, access, and mechanism for each argument. 


The following information is provided for each argument: 


Usage 


The Usage column specifies the general VAX binding argument type. 

For example, if the argument is a resource identifier, the Usage field is 
“identifier.” This field provides additional information about the argument 
that is helpful when declaring the argument within a program. Refer to 
Table 1—2 for a list of usage entries used in Xlib routines. 


Table 1-2. VAX Usage Entries 


Entry Description 

address Unsigned longword containing the virtual address of data 
or code, but not of a procedure entry mask (which is a 
procedure entry). 

array An array with the specific description of its elements provided 
in the argument description. 

Boolean Unsigned longword with the predefined values of 1 for true 
and 0 for false. 

byte A signed byte integer. 

uns byte An unsigned byte integer. 

char string String of 0 to 65,535 8-bit characters. 

cond value Unsigned longword specifying that a predefined condition 
value will be returned in RO. 

identifier A value used to refer to a resource. It is originally returned 
by the system. In the VAX binding, an identifier is a longword 
integer (unsigned). 

longword A signed longword integer 


uns longword 
mask longword 


An unsigned longword integer 
An unsigned longword interpreted as a bit mask. 


procedure Entry mask to a procedure. 

record A data structure with the specific description of the structure 
provided in the argument description. 

word A signed word integer 

uns word An unsigned word integer 

Data Type 


The data type column specifies the standard VAX data type of the 


argument. For example, if the argument is a resource identifier, the data 
type is “longword (unsigned).” If the argument has a predefined value, it 

is provided in the description of the argument. The following are the VAX 
data type entries used in the Xlib routines: 

¢ byte 


¢ character string 
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longword 

longword (unsigned), notated as uns longword 
vector longword 

word (signed) 

word (unsigned), notated as uns word 


The name of a VAX data structure. The following are the valid VAX 
data structure names that can appear in this column: 


x$any_event 

x$are 

x$button_event 
x$char_2b 
x$char_struct 
x$circ_request_event 
x$circulate_event 
x$class_hint 
x$clie_message_event 
x$color 
x$colormap_event 
x$compose_status 
x$conf_request_event 
x$configure_event 
x$creat_window_event 
x$crossing_event 
x$depth 
x$destr_window_event 
x$display 
x$error_event 
x$event 
x$expose_event 
x$ext_codes 
x$ext_data 
x$focus_change_event 
x$font_prop 
x$font_struct 
x$frame 

x$gc_struct 
x$gce_values 
x$graph_expose_event 
x$gravity_event 
x$host_address 
x$icon_size 

x$image 

x$key_event 
x$keyboard_control 
x$keyboard_state 
x$keymap_event 
x$map_event 
x$map_request_event 
x$mapping_event 
x$modifier_keymap 
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x$motion_event 
x$no_expose_event 
x$point 
x$property_event 
x$rectangle 
x$reparent_event 
x$resource_req 
x$resz_request_event 
x$rm_value 
x$screen 
x$screen_format 
x$segment 
x$sel_request_event 
x$select_clear_event 
x$selection_event 
x$set_win_attributes 
x$size_hints 
x$standard_colormap 
x$text_item 
x$text_item_16 
x$time_coord 
x$unmap_event 
x$visibility_event 
x$visual 
x$visual_info 
x$window_attributes 
x$window_changes 
x$wm_hints 


Access 


The access column specifies the way in which the called routine accesses 
the argument. For example, when the argument is passed as input, 

the access is “read only” for both bindings and when the argument is 
returned by the routine, the access is “write only” for both bindings. Refer 
to Table 1—3 for a list of access entries used in the Xlib routines. 


Table 1-3 Access Entries 
Entry Description 


read Input data needed by the routine to perform its operation 
must be readable. When an argument specifies input data, 
the access entry is readable. The routine cannot write data 
back to this argument. 


write Output data returned by the routine to a specific location. 
When an argument specifies output data, the access entry 
is writable. The routine does not read the contents of the 
location either before or after it writes into the location. 


(continued on next page) 
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MIT C Format 


Returns 


Table 1-3 (Cont.) Access Entries 
Entry Description 


read/write or modify The routine reads the input data, which it uses in its 
operation, and then overwrites the input data with the 
results (the output data) of the operation. Thus, when the 
routine completes execution, the input data specified by the 
argument is lost. 


Mechanism 


The mechanism column specifies the passing mechanism used by the 
called routine. For example, when the argument is the value itself, the 
mechanism is “by value” and when the argument is a pointer to the value, 
the mechanism is “by reference.” Refer to Table 1-4 for a complete list of 
mechanism entries used in the Xlib routines. 


Table 1-4 Mechanism Entries 


Entry Description 


value The argument contains the actual data to be used by the 
routine. Note that because an argument is only one longword 
in length, only data that can be represented in one longword 
can be passed by value. 


reference The argument contains the address of the data to be used by 
the routine. The argument is a pointer to the actual data. 
descriptor The argument contains the address of a descriptor. A 


descriptor consists of two or more longwords (depending 
on the type of descriptor used), which describe the location, 
length, and the VAX standard data type of the data to be 
used by the called routine. The argument is a pointer to a 
descriptor that itself is a pointer to the actual data. 


The section contains the MIT C routine call format. The MIT C format 
follows the same conventions listed in Table 1~1, with the exception of the 
routine entry point name. In MIT C, the name is shown in initial capitals 
with the prefix X. The format is followed by the MIT C declarations for 
each argument. 


Most routines return a value. This section describes what the returned 
value specifies. In the VAX binding, the first item in the argument table 
describes how to declare the return value. In the MIT C binding, the 
declaration for the return value is the first item in the declaration list. If 
a routine does not have a return value, this section is omitted. 


1.1.6 


1.1.7 


1.1.8 


1.2 
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Argument Information 


Description 


X Errors 


Data Structures 


Detailed descriptions of each argument follow the Returns section. These 
descriptions cover what the arguments specify and any predefined values. 


This section describes how to use the routine. Generally, the topics covered 
can include what the routine is used for, how it is processed, other routines 
to use before or after it, other routines to use to accomplish similar tasks, 
and any other useful routine-specific information. For a more tutorial 
description of how to use the Xlib routines, see VMS DECwindows Xlib 
Programming Volume. 


This section lists the X errors that the routine can return. An X error 
event is generated by the server when it detects erroneous or inconsistent 
information in a client request. Error events contain an error code that 
tells the client what problem the server has with the request; for instance, 
X$C_BAD_VALUE or BadValue would indicate a problem with the value 
of some setting in the request. The X errors section contains a table that 
lists the VAX and MIT C names for the error and a description of the error. 


The X error description sections for utility routines list only the first-level 
errors that the routines can generate. The utility routines may indirectly 
generate additional errors if they call protocol requests that fail. 





Predefined data structures are provided for complex data structures used 
by Xlib routines. The data structures are presented in the overview section 
for each functional group of routines. They are presented in two formats: 


* VAX binding format—tThe data structure in a generic VAX language. 
The generic language provides the VAX binding names for the data 
structure and individual fields within the data structure. It also 
provides the basic VAX data type for each field. The data type used for 
a specific language must be subsequently derived. For information on 
how to derive the data type for each supported VAX language, see the 
Introduction to VMS System Routines in the VMS documentation set. 


¢ MIT C binding format—The data structure in the MIT C programming 
language. 


For consistency, this manual refers to fields in data structures as 
members. 
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1.3 Protocol Request and Utility Routines 


Although many Xlib routines make protocol requests directly, some do 
not. Xlib routines that do make protocol requests directly are called the 
protocol routines; those that do not are called the utility routines. The 
utility routines make certain programming tasks easier. 
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For example, you can create clip areas using two routines: SET CLIP 
RECTANGLES or SET REGION. SET CLIP RECTANGLES is a protocol 
routine because it calls the SetClipRectangles protocol request directly. 
SET REGION is a utility routine because it calls the Xlib routine SET 
CLIP RECTANGLES, which then calls the SetClipRectangles protocol 


request. 


Table 1-5 lists each Xlib routine. If the routine makes a direct protocol 
request, the name of the protocol request is listed. If it is a utility routine, 
the term “Utility” appears. Only the Xlib routines are documented in this 
reference manual, not the protocol requests. 


Table 1-5 Protocol and Utility Routines 


Xlib Routine 


ACTIVATE SCREEN SAVER 
ADD HOST 

ADD HOSTS 

ADD PIXEL 

ADD TO SAVE SET 
ALLOC COLOR 

ALLOC COLOR CELLS 
ALLOC COLOR PLANES 
ALLOC NAMED COLOR 
ALLOW EVENTS 

ALL PLANES 

AUTO REPEAT OFF 

AUTO REPEAT ON 

BELL 

BITMAP BIT ORDER 
BITMAP PAD 

BITMAP UNIT 

BLACK PIXEL 

BLACK PIXEL OF SCREEN 
CELLS OF SCREEN 
CHANGE ACTIVE POINTER GRAB 
CHANGE GC 


Protocol Request or Utility Routine 


ForceScreenSaver 
ChangeHosts 
ChangeHosts 

Utility 

ChangeSaveSet 
AllocColor 
AllocCoiorCells 
AllocColorPlanes 
AllocNamedColor 
AllowEvents 

Utility 
ChangeKeyboardConitrol 
ChangeKeyboardControl 
Bell 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 
ChangeActivePointerGrab 
ChangeGC 


(continued on next page) 
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Xlib Routine 


CHANGE KEYBOARD CONTROL 
CHANGE KEYBOARD MAPPING 
CHANGE POINTER CONTROL 
CHANGE PROPERTY 

CHANGE SAVE SET 

CHANGE WINDOW ATTRIBUTES 
CHECK IF EVENT 

CHECK MASK EVENT 

CHECK TYPED EVENT 

CHECK TYPED WINDOW EVENT 
CHECK WINDOW EVENT 
CIRCULATE SUBWINDOWS 
CIRCULATE SUBWINDOWS DOWN 
CIRCULATE SUBWINDOWS UP 
CLEAR AREA 

CLEAR WINDOW 

CLIP BOX 

CLOSE DISPLAY 

CONFIGURE WINDOW 
CONNECTION NUMBER 
CONVERT SELECTION 

COPY AREA 

COPY COLORMAP AND FREE 
COPY GC 

COPY PLANE 

CREATE BITMAP FROM DATA 
CREATE COLORMAP 

CREATE FONT CURSOR 
CREATE GC 

CREATE GLYPH CURSOR 
CREATE IMAGE 

CREATE PIXMAP 

CREATE PIXMAP CURSOR 


CREATE PIXMAP FROM BITMAP 
DATA 


CREATE REGION 


Protocol Request or Utility Routine 


ChangeKeyboardControl 
ChangeKeyboardMapping 
ChangePointerControl 
ChangeProperty 
ChangeSaveSet 
ChangeWindowAttributes 
Utility 

Utility 

Utility 

Utility 

Utility 

CirculateWindow 
CirculateWindow 
CirculateWindow 
ClearArea 

ClearArea 

Utility 

Utility 

ConfigureWindow 

Utility 

ConvertSelection 
CopyArea 
CopyColormapAndFree 
CopyGC 

CopyPiane 

CreateGC, CreatePixmap, FreeGC, Putlmage 
CreateColormap 
CreateGlyphCursor 
CreateGC 
CreateGlyphCursor 
Utility 

CreatePixmap 
CreateCursor 

CreateGC, CreatePixmap, FreeGC, Putimage 


Utility 


(continued on next page) 
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Table 1-5 (Cont.) Protocol and Utility Routines 


Xiib Routine Protocol Request or Utility Routine 
CREATE SIMPLE WINDOW Create Window 
CREATE WINDOW CreateWindow 
DEFAULT COLORMAP Utility 

DEFAULT COLORMAP OF SCREEN _ Utility 

DEFAULT DEPTH Utility 

DEFAULT DEPTH OF SCREEN Utility 

DEFAULT GC Utility 

DEFAULT GC OF SCREEN Utility 

DEFAULT ROOT WINDOW Utility 

DEFAULT SCREEN Utility 

DEFAULT SCREEN OF DISPLAY Utility 

DEFAULT VISUAL Utility 

DEFAULT VISUAL OF SCREEN Utility 

DEFINE CURSOR ChangeWindowAttributes 
DELETE CONTEXT Utility 

DELETE MODIFIER MAP ENTRY Utility 

DELETE PROPERTY DeleteProperty 
DESTROY IMAGE Utility 

DESTROY REGION Utility 

DESTROY SUBWINDOWS DestroySubwindows 
DESTROY WINDOW DestroyWindow 
DISABLE ACCESS CONTROL SetAccessControl 
DISPLAY CELLS Utility 

DISPLAY HEIGHT Utility 

DISPLAY HEIGHT MM Utility 

DISPLAY NAME Utility 

DISPLAY OF SCREEN Utility 

DISPLAY PLANES Utility 

DISPLAY STRING Utility 

DISPLAY WIDTH Utility 

DISPLAY WIDTH MM Utility 

DOES BACKING STORE Utility 

DOES SAVE UNDERS Utility 

DRAW ARC PolyArc 

DRAW ARCS PolyArc 

DRAW IMAGE STRING ImageText8 





{continued on next page) 
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Table 1-5 (Cont.) Protocol and Utility Routines 


Xlib Routine 


DRAW IMAGE STRING 16 
DRAW LINE 

DRAW LINES 

DRAW POINT 

DRAW POINTS 

DRAW RECTANGLE 

DRAW RECTANGLES 

DRAW SEGMENTS 

DRAW STRING 

DRAW STRING 16 

DRAW TEXT 

DRAW TEXT 16 

EMPTY REGION 

ENABLE ACCESS CONTROL 
EQUAL REGION 

EVENT MASK OF SCREEN 
EVENTS QUEUED 

FETCH BUFFER 

FETCH BYTES 

FETCH NAME 

FILL ARC 

FILL ARCS 

FILL POLYGON 

FILL RECTANGLE 

FILL RECTANGLES 

FIND CONTEXT 

FLUSH 

FORCE SCREEN SAVER 
FREE 

FREE COLORMAP 

FREE COLORS 

FREE CURSOR 

FREE FONT 

FREE FONT INFO (MIT C only) 
FREE FONT NAMES (MIT C only) 
FREE FONT PATH (MIT C only) 


Protocol Request or Utility Routine 


Image Text16 
PolySegment 
PolyLine 
PolyPoint 
PolyPoint 
PolyRectangle 
PolyRectangle 
PolySegment 
PolyText8 
PolyText16 
PolyText8 
PolyText16 

Utility 
SetAccessControl 
Utility 

Utility 

Utility 

Utility 
GetProperty 
GetProperty 
PolyFillArc 
PolyFillArc 
FillPoly 
PolyFillRectangle 
PolyFillRectangle 
Utility 

Utility 
ForceScreenSaver 
Utility 
FreeColormap 
FreeColors 
FreeCursor 
CloseFont 

Utility 

Utility 

Utility 
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Xlib Routine 


FREE GC 

FREE MODIFIERMAP 

FREE PIXMAP 

GCONTEXT FROM GC 
GEOMETRY 

GET ATOM NAME 

GET CHAR INFO (VAX only) 
GET CHAR STRUCT (VAX only) 
GET CLASS HINT 

GET DEFAULT 

GET ERROR DATABASE TEXT 
GET ERROR TEXT 

GET FONT PATH 

GET FONT PROPERTY 
GET GEOMETRY 

GET ICON NAME 

GET ICON SIZES 

GET IMAGE 

GET INPUT FOCUS 

GET KEYBOARD CONTROL 
GET KEYBOARD MAPPING 
GET MODIFIER MAPPING 
GET MOTION EVENTS 

GET NORMAL HINTS 

GET PIXEL 

GET POINTER CONTROL 
GET POINTER MAPPING 
GET SCREEN SAVER 

GET SELECTION OWNER 
GET SIZE HINTS 

GET STANDARD COLORMAP 
GET SUBIMAGE 

GET TRANSIENT FOR HINT 
GET VISUAL INFO 

GET WINDOW ATTRIBUTES 
GET WINDOW PROPERTY 


Protocol Request or Utility Routine 


FreeGC 

Utility 

FreePixmap 

Utility 

Utility 
GetAtomName 
Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

GetFontPath 

Utility 

GetGeometry 

Utility 

GetProperty 
Getlmage 
GetinputFocus 
GetKeyboardControl 
GetKeyboardMapping 
GetModifierMapping 
GetMotionEvents 
GetProperty 

Utility 
GetPointerControl 
GeiPointerMapping 
SetScreenSaver 
GetSelectionOwner 
GetProperty 

Utility 

Utility 

Utility 

Utility 
GetWindowAttributes 
GetProperty 
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Xlib Routine 


GET WM HINTS 

GET ZOOM HINTS 

GRAB BUTTON 

GRAB KEY 

GRAB KEYBOARD 

GRAB POINTER 

GRAB SERVER 

HEIGHT MM OF SCREEN 
HEIGHT OF SCREEN 

IF EVENT 

IMAGE BYTE ORDER 
INSERT MODIFIERMAP ENTRY 
INSTALL COLORMAP 
INTERN ATOM 
INTERSECT REGION 
KEYCODE TO KEYSYM 
KEYSYM TO KEYCODE 
KEYSYM TO STRING 
KILL CLIENT 


LAST KNOWN REQUEST 
PROCESSED 


LIST FONT (VAX only) 

LIST FONTS 

LIST FONT WITH INFO (VAX only) 
LIST FONTS WITH INFO 

LIST HOSTS 

LIST INSTALLED COLORMAPS 
LIST PROPERTIES 

LOAD FONT 

LOAD QUERY FONT 

LOOKUP COLOR 

LOOKUP KEYSYM 

LOOKUP STRING 

LOWER WINDOW 

MAP RAISED 

MAP SUBWINDOWS 


Protocol Request or Utility Routine 


GetProperty 
GetProperty 
GrabButton 
GrabKey 
GrabKeyboard 
GrabPointer 
GrabServer 
Utility 

Utility 

Utility 

Utility 

Utility 
InstallColormap 
InternAtom 
Utility 

Utility 

Utility 

Utility 
KillClient 
Utility 


ListFonts 

ListFonts 
ListFontsWithInfo 
ListFontsWithInfo 
ListHosts 
ListinstalledColormaps 
ListProperties 
OpenFont 

OpenFont, QueryFont 
LookupColor 

Utility 

Utility 
ConfigureWindow 
ConfigureWindow, MapWindow 
MapSubwindows 
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Xlib Routine 


MAP WINDOW 
MASK EVENT 
MATCH VISUAL INFO 


MAX CMAPS OF SCREEN 
MIN CMAPS OF SCREEN 


MOVE RESIZE WINDOW 
MOVE WINDOW 

NEW MODIFIERMAP 
NEXT EVENT 

NEXT REQUEST 

NO OP 

OFFSET REGION 
OPEN DISPLAY 
PARSE COLOR 
PARSE GEOMETRY 
PEEK EVENT 

PEEK IF EVENT 
PENDING 
PERMALLOC 

PLANES OF SCREEN 
POINT IN REGION 
POLYGON REGION 
PROTOCOL REVISION 
PROTOCOL VERSION 
PUT BACK EVENT 
PUT IMAGE 

PUT PIXEL 

Q LENGTH 

QUERY BEST CURSOR 
QUERY BEST SIZE 
QUERY BEST STIPPLE 
QUERY BEST TILE 
QUERY COLOR 
QUERY COLORS 
QUERY FONT 

QUERY KEYMAP 


Protocol Request or Utility Routine 


MapWindow 
Utility 

Utility 

Utility 

Utility 
ConfigureWindow 
ConfigureWindow 
Utility 

Utility 

Utility 
NoOperation 
Utility 
CreateGC 
LookupColor 
Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 
Puilmage 
Utility 

Utility 
QueryBestSize 
QueryBestSize 
QueryBestSize 
QueryBestSize 
QueryColors 
QueryColors 
Utility 

Utility 
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QUERY POINTER 

QUERY TEXT EXTENTS 
QUERY TEXT EXTENTS 16 
QUERY TREE 

RAISE WINDOW 

READ BITMAP FILE 

REBIND KEYSYM 

RECOLOR CURSOR 

RECT IN REGION 

REFRESH KEYBOARD MAPPING 
REMOVE FROM SAVE SET 
REMOVE HOST 

REMOVE HOSTS 

REPARENT WINDOW 

RESET SCREEN SAVER 
RESIZE WINDOW 

RESTACK WINDOWS 

RM GET FILE DATABASE 

RM GET RESOURCE 

RM GET STRING DATABASE 
RM INITIALIZE 

RM MERGE DATABASES 

RM PARSE COMMAND 

RM PUT FILE DATABASE 

RM PUT LINE RESOURCE 

RM PUT RESOURCE 

RM PUT STRING RESOURCE 
RM Q GET RESOURCE 

RM Q GET SEARCH LIST 

RM Q GET SEARCH RESOURCE 
RM Q PUT RESOURCE 

RM Q PUT STRING RESOURCE 
RM QUARK TO STRING 

RM STRING TO BIND QUARK LIST 
RM STRING TO QUARK 

RM STRING TO QUARK LIST 


Protocol Request or Utility Routine 


QueryPointer 
QueryTextExtents 
QueryTextExtents 
QueryTree 
ConfigureWindow 
CreateGC, CreatePixmap, FreeGC, Putlmage 
Utility 
RecolorCursor 
Utility 

Utility 
ChangeSaveSet 
ChangeHosts 
ChangeHosts 
ReparentWindow 
ForceScreenSaver 
ConfigureWindow 
ConfigureWindow 
Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 
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Xlib Routine 


RM UNIQUE QUARK 

ROOT WINDOW 

ROOT WINDOW OF SCREEN 
ROTATE BUFFERS 


ROTATE WINDOW PROPERTIES 


SAVE CONTEXT 
SCREEN COUNT 
SCREEN OF DISPLAY 
SELECT ASYNC EVENT 
SELECT ASYNC INPUT 
SELECT INPUT 

SEND EVENT 

SERVER VENDOR 

SET ACCESS CONTROL 
SET AFTER FUNCTION 
SET ARC MODE 

SET BACKGROUND 
SET CLASS HINT 

SET CLIP MASK 

SET CLIP ORIGIN 

SET CLIP RECTANGLES 
SET CLOSE DOWN MODE 
SET COMMAND 

SET DASHES 

SET ERROR HANDLER 
SET FILL RULE 

SET FILL STYLE 

SET FONT 

SET FONT PATH 

SET FOREGROUND 
SET FUNCTION 

SET GRAPHICS EXPOSURES 
SET ICON NAME 

SET ICON SIZES 

SET INPUT FOCUS 

SET 1O ERROR HANDLER 
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Utility 

Utility 

Utility 
RotateProperties 
RotateProperties 
Utility 

Utility 

Utility 

Utility 

Utility 
ChangeWindowAttributes 
SendEvent 

Utility 
SetAccessControl 
Utility 

ChangeGC 
ChangeGC 

Utility 

ChangeGC 
ChangeGC 
SetClipRectangles 
SetCloseDownMode 
ChangeProperty 
SetDashes 

Utility 

ChangeGC 
ChangeGC 
ChangeGC 
SetFontPath 
ChangeGC 
ChangeGC 
ChangeGC 

Utility 
ChangeProperty 
SetlnputFocus 
Utility 
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SET LINE ATTRIBUTES 

SET MODIFIER MAPPING 
SET NORMAL HINTS 

SET PLANE MASK 

SET POINTER MAPPING 

SET REGION 

SET SCREEN SAVER 

SET SELECTION OWNER 
SET SIZE HINTS 

SET STANDARD COLORMAP 
SET STANDARD PROPERTIES 
SET STATE 

SET STIPPLE 

SET SUBWINDOW MODE 
SET TILE 

SET TRANSIENT FOR HINT 
SET TS ORIGIN 

SET WINDOW BACKGROUND 


SET WINDOW BACKGROUND 
PIXMAP 


SET WINDOW BORDER 

SET WINDOW BORDER PIXMAP 
SET WINDOW BORDER WIDTH 
SET WINDOW COLORMAP 
SET WM HINTS 

SET ZOOM HINTS 

SHRINK REGION 

STORE BUFFER 

STORE BYTES 

STORE COLOR 

STORE COLORS 

STORE NAME 

STORE NAMED COLOR 
STRING TO KEYSYM 
SUBIMAGE 

SUBTRACT REGION 
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ChangeGC 
SetModifierMapping 
ChangeProperty 
ChangeGC 
SetPointerMapping 

Utility 

SetScreenSaver 
SetSelectionOwner 
ChangeProperty 

Utility 

ChangeProperty 
ChangeGC 

ChangeGC 

ChangeGC 

ChangeGC 

Utility 

ChangeGC 
ChangeWindowAttributes 
ChangeWindowAttributes 


ChangeWindowAttributes 
ChangeWindowAttributes 
ConfigureWindow 
ChangeWindowAittributes 
ChangeProperty 
ChangeProperty 

Utility 

ChangeProperty 
ChangeProperty 
StoreColors 

StoreColors 
ChangeProperty 
StoreNamedColor 

Utility 

Utility 

Utility 
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SYNC 

SYNCHRONIZE 

TEXT EXTENTS 

TEXT EXTENTS 16 

TEXT WIDTH 

TEXT WIDTH 16 
TRANSLATE COORDINATES 
UNDEFINE CURSOR 
UNGRAB BUTTON 
UNGRAB KEY 

UNGRAB KEYBOARD 
UNGRAB POINTER 
UNGRAB SERVER 
UNINSTALL COLORMAP 
UNION RECT WITH REGION 
UNION REGION 

UNIQUE CONTEXT 
UNLOAD FONT 

UNMAP SUBWINDOWS 
UNMAP WINDOW 
VENDOR RELEASE 

WARP POINTER 

WHITE PIXEL 

WHITE PIXEL OF SCREEN 
WIDTH MM OF SCREEN 
WIDTH OF SCREEN 
WINDOW EVENT 

WRITE BITMAP FILE 

XOR REGION 
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GetInputFocus 
Utility 

Utility 

Utility 

Utility 

Utility 
TranslateCoordinates 
ChangeWindowAttributes 
UngrabButton 
UngrabKey 
UngrabKeyboard 
UngrabPointer 
UngrabServer 
UninstallColormap 
Utility 

Utility 

Utility 

CloseFont 
UnmapSubwindows 
UnmapWindow 
Utility 

WarpPointer 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 

Utility 
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Display Routines 


This chapter includes routines that open and close a display, provide 
information about an open display, and manipulate buffers. 


The Xlib routines allow you to perform window operations on any 
supported display in a network. You can think of a display as the 
connection between a client program and an instance of the X server. 


Client programs can run in any CPU in the network and open explicit 
connections to displays to perform input and output. The X server is said 
to control the display because it maintains client status information, such 
as the state of the graphics context, and manages input and output for the 
connection. Client programs can open connections to one or more displays 
at one time; X servers can maintain multiple client connections at one 
time. 


For example, an instructor who wants to draw a box on all displays in 
a class could write a program that opened a connection to each display. 
This program could use its event mask to accept input from one or more 
of the connections. For more information about creating an event mask, 
see Chapter 4. If the students in the class write programs that open 
connections to their own displays, their instance of the server prioritizes 
the client requests and schedules them accordingly. 


Xlib routines provide functions that allow you to specify the display on 
which you want to perform window operations. Xlib also provides C 
language macros that return information about a specific display. This 
section describes routines that enable you to perform the following 
operations: 


¢ Open (connect to) a display 
¢ Obtain information about a display 


¢ Close (disconnect) a display 


For concepts related to display routines and information on how to use 
display routines, see VMS DECwindows Xlib Programming Volume. 


The routines described in this chapter are listed in Table 2-1. 


Table 2-1 Display Routines 


Routine Name Description 

ALL PLANES Returns a value with all bits set on. This value 
can then be used in a plane argument to a 
procedure. 
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BITMAP BIT ORDER 


BITMAP PAD 


BITMAP UNIT 
BLACK PIXEL 


BLACK PIXEL OF SCREEN 
CELLS OF SCREEN 


CLOSE DISPLAY 


CONNECTION NUMBER 
DEFAULT COLORMAP 


DEFAULT COLORMAP OF SCREEN 


DEFAULT DEPTH 


DEFAULT DEPTH OF SCREEN 


DEFAULT GC 


DEFAULT GC OF SCREEN 


DEFAULT ROOT WINDOW 


DEFAULT SCREEN 


DEFAULT SCREEN OF DISPLAY 


DEFAULT VISUAL 


DEFAULT VISUAL OF SCREEN 


DISPLAY CELLS 


DISPLAY HEIGHT 


DISPLAY HEIGHT MM 


Description 


Returns the value of the leftmost bit in a 
bitmap. 


Returns a number of bits by which all scan 
lines must be padded. 


Returns the size of a bitmap’s unit. 


Returns the color index (pixel value) that yields 
black on the specified screen. 


Returns the black pixel of the specified screen. 


Returns the number of color map cells on the 
specified screen. 


Closes a connection between a client program 
and the display that you specify. 


Returns the connection number of the display. 


Returns the default color map for allocation on 
the specified screen. 


Returns the default color map of the specified 
screen. 


Returns the depth of the default root window 
for the specified screen. 


Returns the default depth of the specified 
screen. 


Returns the default graphics context for the 
root window of the specified screen. 


Returns the default graphics context of the 
specified screen. 


Returns the default root window for a specified 
display. 


Returns the default screen referenced in 
OPEN DISPLAY. 


Returns the default screen of the specified 
display. 


Returns the default visual type for the specified 
screen. 


Returns the default visual of the specified 
screen. 


Returns the number of color map cells on the 
specified screen. 


Returns a number that specifies the height of 
the screen in pixels. 


Returns a number that specifies the height of 
the screen in millimeters. 
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DISPLAY NAME 


DISPLAY PLANES 


DISPLAY STRING 


DISPLAY WIDTH 


DISPLAY WIDTH MM 


DOES BACKING STORE 


DOES SAVE UNDERS 


DISPLAY OF SCREEN 
EVENT MASK OF SCREEN 


HEIGHT MM OF SCREEN 


HEIGHT OF SCREEN 


IMAGE BYTE ORDER 


LAST KNOWN REQUEST 
PROCESSED 


MAX CMAPS OF SCREEN 


MIN CMAPS OF SCREEN 


NEXT REQUEST 


OPEN DISPLAY 


PLANES OF SCREEN 


PROTOCOL REVISION 


PROTOCOL VERSION 


Description 


Returns the name of the display that you were 
trying to open. 

Returns the number of planes on the specified 
screen. 


Returns the name of the string that was 
passed to OPEN DISPLAY when the current 
display was opened. 


Returns a number that specifies the width of 
the screen in pixels. 


Returns a number that specifies the width of 
the screen in millimeters. 


Returns a value that indicates whether the 
screen supports backing stores. 


Returns a Boolean value that indicates 
whether the screen supports save unders. 


Returns the display of the specified screen. 


Returns the initial root event mask of the 
specified screen. 


Returns the height, in millimeters, of the 
specified screen. 


Returns the height, in pixels, of the specified 
screen. 


The required byte order for images for each 
scan line unit in XYFormat (bitmap) or for each 
pixel value in ZFormat. 


Extracts the serial number of the last request 
known by Xlib to have been processed to the 
X server. 


Returns the maximum number of color maps 
supported by the specified screen. 


Returns the minimum number of color maps 
supported by the specified screen. 


Extracts the serial number that is to be used 
for the next request. 


Opens a connection between a client program 
and the display that you specify. 


Returns the number of planes in the specified 
screen. 


Returns the minor protocol revision number 
that the X server is using. 


Returns the version number of the X protocol 
associated with the connected display. 
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Routine Name 


Q LENGTH 


ROOT WINDOW 
ROOT WINDOW OF SCREEN 


ROTATE BUFFERS 
SCREEN COUNT 
SCREEN OF DISPLAY 


SERVER VENDOR 


STORE BUFFER 
STORE BYTES 
VENDOR RELEASE 


WHITE PIXEL 


WHITE PIXEL OF SCREEN 
WIDTH MM OF SCREEN 


WIDTH OF SCREEN 


Description 


Returns the length of the input queue for the 
connected hardware display. 


Returns the identifier of the root window. 


Returns the root window of the specified 
screen. 


Rotates the ring of cut buffers from 0 to 7. 
Returns the number of available screens. 


Returns a pointer to the screen of the specified 
display. 


Returns a pointer to a string that identifies the 
owner of the X server implementation. 


Stores data in a specified cut buffer. 
Stores data in cut buffer zero. 


Returns the number of the release of the X 
server, as assigned by the vendor. 


Returns the color index (pixel value) that yields 
white on the specified screen. 


Returns the white pixel of the specified screen. 


Returns the width, in millimeters, of the 
specified screen. 


Returns the width, in pixels, of the specified 
screen. 
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ALL PLANES 


Reiurns a value with all bits set on. This value can then be used in a plane 
argument to a procedure. 





VAX FORMAT _ value_return = X$ALL_PLANES 


argument 


information Aigunen sete Gala lps Aes echanien 


value_return uns longword uns longword write value 





MIT C FORMAT =ssvalue_return = XAIIPlanes 





argument 
information unsigned long XA11Planes() 
RETURNS value_return 


The returned value with all bits set to 1. 





DESCRIPTION ALL PLANES returns a value with all bits set on. This value can then be 
used in a plane argument to a procedure. 
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BITMAP BIT ORDER 


Returns whether the bits in a bitmap are ordered with the least significant bit 
first or the most significant bit first. 





VAX FORMAT _ order_return = X$BITMAP_BIT_ORDER (display) 


argument 

information Argument Usage Data Type Access Mechanism 
order_return longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT order_return = XBitmapBitOrder (display) 





argument 

information int XBitmapBitOrder (display) 
Display *display; 

RETURNS order_return 


The value of the leftmost bit in the bitmap, as displayed on the screen. 
Valid values are shown in the following table: 


VAX Cc Description 

X$C_LSB_FIRST LSBFirst The least significant bit is displayed first. 
X$C_MSB_ MSBFirst The most significant bit is displayed first. 
FIRST 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION _ BITMAP BIT ORDER returns whether the bits in a bitmap are ordered 
with the least significant bit first or the most significant bit first. Within 
each bitmap unit, the leftmost bit in the bitmap (as displayed on the 
screen) is either the least significant bit or the most significant bit in the 
bitmap unit. 
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BITMAP PAD 


Returns a number of bits by which all scan lines must be padded. 





VAX FORMAT __ pad_return=X$BITMAP_PAD (display) 


argument 


information Argument ‘Usage —‘dDataType_=~=—SsAccess._—~—Ss Mechanism __ 


pad_return longword longword write value 
display identifier uns longword read reference 





MITC FORMAT pad_return=XBitmapPad (display) 





argument 
Display *display; 
RETURNS pad_return 


The number of bits by which all scan lines must be padded. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION _ BITMAP PAD returns a multiple of bits by which all scan lines must be 
padded. When an image is sent to the server, the number of bits in each 
scan line must be a multiple of pad_return. If the number of bits in 
the scan line is greater than the number of bits in the image, the server 
ignores the extra bits. 
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BITMAP UNIT 


Returns the size of a bitmap’s unit. 





VAX FORMAT _ size_return=X$BITMAP_UNIT (display) 


argument 


information Argument Usage —-DataType = Access_~=— Mechanism _ 


size_return uns longword uns longword write value 
display identifier uns longword read reference 





MIT C FORMAT ss size_return = XBitmapUnit (display) 





argument 

information int XBitmapUnit (display) 
Display *display; 

RETURNS size_return 


The size, in bits, of the bitmap’s unit. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION BITMAP UNIT returns the size, in bits, of a bitmap’s unit. This value can 
equal 8, 16, or 32. When an image is sent to the server, the server receives 
the image in units of the number of bits specified in BITMAP UNIT. 
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BLACK PIXEL 


Returns the color index (pixel value) that yields black on the specified screen. 





VAX FORMAT _ color_index_return = X$BLACK_PIXEL 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
color_index_return identifier uns longword write value 
display identifier uns longword read reference 
screen_number uns longword —_ uns longword read reference 





MIT C FORMAT color_index_return = XBlackPixel 
(display, screen_number) 





argument 

information unsigned long XBlackPixel (display, screen_number) 
Display *display; 
int screen_number; 

RETURNS color_index_return 


The identifier of the color index (pixel value) that yields black on the 
specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which the black pixel is requested. 





DESCRIPTION BLACK PIXEL returns the color index (pixel value) that yields black on 
the specified screen. 


To obtain the color index (pixel value) that yields white on a specified 
screen, use WHITE PIXEL. 
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BLACK PIXEL OF SCREEN 


Returns the black pixel of the specified screen. 





VAX FORMAT _ color_index_return = X$BLACK_PIXEL_OF_SCREEN 
(screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
color_index_return identifier uns longword write value 
screen_id identifier uns longword read reference 





MITC FORMAT color_index_return = XBlackPixelOfScreen 
(screen_id) 





argument 

information unsigned long XBlackPixelOfScreen(screen_id) 
Screen *screen_id; 

RETURNS color_index_return 


The identifier of the color index (pixel value) that yields black on the 
specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the black pixel is requested. 





DESCRIPTION BLACK PIXEL OF SCREEN returns the black pixel of the specified 
screen. 


To obtain the white pixel of a specified screen, use WHITE PIXEL OF 
SCREEN. 
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CELLS OF SCREEN 


Returns the number of color map cells on the specified screen. 





VAX FORMAT _ cells_return = X$CELLS_OF_SCREEN 
(screen_id) 


argument 


information Argument Usage —~—‘DataType + Access_~=—=—S=<wMechanism _ 


cells_return longword longword longword write 
screen_id identifier uns longword read reference 





MIT C FORMAT celis_return = XCellsOfScreen 
(screen_id) 





argument 

information int XCellsOfScreen(screen_id) 
Screen screen_id; 

RETURNS cells_return 


The number of color map cells on the specified screen. 





ARGUMENTS __ screen_id 
The identifier of the screen for which the number of color map cells is 
requested. 





DESCRIPTION CELLS OF SCREEN returns the number of color map cells on the specified 
screen. 
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CLOSE DISPLAY 


Closes a connection between a client program and the display that you 
specify. 





VAXFORMAT X$CLOSE_DISPLAY (display) 


argument 


information Argument ‘Usage —=—~Data Type ==» Access._~=—s Mechanism _ 


display identifier uns longword read reference 





MITC FORMAT XCloseDisplay (display) 


argument 


information XCloseDisplay (display) 
Display *display; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION CLOSE DISPLAY disconnects a client’s connection to the display specified 
in the display identifier. OPEN DISPLAY returned a pointer to the display 
identifier when it opened the display. 


CLOSE DISPLAY destroys all windows created by the client, resource 
identifiers (Window, Font, Pixmap, Colormap, Cursor, and GContext), or 
other resources (such as graphics contexts) that the client application has 
created on this display, unless the closedown mode of the resource has 
been changed. Therefore, these windows, resource identifiers, and other 
resources should never be referenced again. In addition, CLOSE DISPLAY 
discards any output events that have been buffered but have not yet been 
sent. Because these operations automatically (implicitly) occur if a process 
exits, you normally do not need to call CLOSE DISPLAY explicitly. 


The server performs a number of automatic operations when its connection 
to the display hardware closes. These operations are described in VMS 
DECwindows Xlib Programming Volume. 


Display Routines 
CLOSE DISPLAY 





X ERRORS 





VAX Cc Description 





X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


2-13 


Display Routines 
CONNECTION NUMBER 


CONNECTION NUMBER 


Returns an integer identifying the connection. 





VAX FORMAT int =X$CONNECTION NUMBER (display) 


argument 


information Argument Usage —=—Data Type «Access. = Mechanism _ 


int longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT int=XConnectionNumber (display) 





argument 

information int ConnectionNumber (display) 
Display *display; 

RETURNS int 


The connection number of the specified display. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION CONNECTION NUMBER returns an integer that identifies the 
connection. This routine is defined to be operating system specific by 
MIT, and there is no direct analogue to the Unix file descriptor in VMS. 


Display Routines 
DEFAULT COLORMAP 


DEFAULT COLORMAP 


Returns the default color map for allocation on the specified screen. 





VAX FORMAT _ colormap_id_return = X${DEFAULT_COLORMAP 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
colormap_id_return identifier longword write value 
display identifier uns longword read reference 
screen_number uns longword uns longword read reference 





MIT C FORMAT colormap_id_return = XDefaultColormap 
(display, screen_number) 





argument 

information Colormap XDefaultColormap(display, screen_number) 
Display *display; 
int screen_number; 

RETURNS colormap_id_return 


The identifier of the default color map for the specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which the default color map is being 
requested. 





DESCRIPTION $=ODEFAULT COLORMAP returns the identifier of the default color map for 
the specified screen. Most applications should allocate pixel values out of 
this color map. 


Display Routines 
DEFAULT COLORMAP OF SCREEN 


DEFAULT COLORMAP OF SCREEN 


Returns the default color map of the specified screen. 





VAX FORMAT ~ colormap_id_return = 
X$DEFAULT_COLORMAP_OF_SCREEN 
(screen_id) 


argument 


information Argument +~—~—~—s<Usage_~=—S@Data Type —-—«~ Access‘ Mechanism _ 


colormap_id_return identifier uns longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT colormap_id_return = XDefaultColormapOfScreen 
(screen_id) 





argument 

information Colormap XDefaultColormapOfScreen(screen_id) 
Screen *screen_id; 

RETURNS colormap_id_return 


The identifier of the default color map of the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the colormap is requested. 





DESCRIPTION i$=DEFAULT COLORMAP OF SCREEN returns the default color map of the 
specified screen. 


Display Routines 
DEFAULT DEPTH 


DEFAULT DEPTH 


Returns the depth of the default root window for the specified screen. 





VAX FORMAT —  depth_return = X$DEFAULT_DEPTH 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
depth_return uns longword uns longword write value 
display identifier uns longword read reference 
screen_number —_ uns longword uns longword read reference 





MITC FORMAT depth_return = XDefaultDepth 
(display, screen_number) 





argument 
information int XDefaultDepth(display, screen_number) 
Display *display; 
int screen number; 
RETURNS depth_return 
The depth (number of planes) of the default root window for the specified 
screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen associated with the default color map used. 





DESCRIPTION DEFAULT DEPTH returns the number of planes of the default root 
window for the specified screen. The identifier of the root window was 
originally returned by ROOT WINDOW. 
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Display Routines 
DEFAULT DEPTH OF SCREEN 


DEFAULT DEPTH OF SCREEN 


Returns the default depth of the specified screen. 





VAX FORMAT —  depth_return =X$DEFAULT_DEPTH_OF_SCREEN 
(screen_id) 


argument 


information Argument Usage —‘Data Type == Access ~=—s Mechanism _ 


depth_return longword longword write value 
screen_id identifier uns longword read reference 





MITC FORMAT depth_return =XDefaultDepthOfScreen 
(screen_id) 





argument 

information int XDefaultDepthOfScreen(screen_id) 
Screen *screen_id; 

RETURNS depth_return 


The default depth, in pixels, of the specified screen. 





ARGUMENTS __ screen_id 
The identifier of the screen for which the depth is requested. 





DESCRIPTION DEFAULT DEPTH OF SCREEN returns the default depth, in pixels, of 
the specified screen. 


Display Routines 





DEFAULT GC 

Returns the default graphics context for the root window of the specified 
screen. 

VAX FORMAT _— context_id_return = X$DEFAULT_GC 

(display, screen_number) 

argument 

information Argument Usage Data Type Access Mechanism 
context_id_return identifier uns longword write value 
display identifier uns longword read reference 
screen_number identifier uns longword read reference 





MIT C FORMAT context_id_return = XDefaultGC 
(display, screen_number) 





argument 
information GC XDefaultGC(display, screen_number) 
Display *display; 
int screen_number; 
RETURNS context_id_return 


The identifier of the default graphics context for the root window of the 
specified screen. 





ARGUMENTS -~—_ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen associated with the graphics context. 





DESCRIPTION DEFAULT GC returns the identifier of the default graphics context for the 
root window of the specified screen. 


If you change the default graphics context using the CHANGE GC, SET 
CLIP RECTANGLES, or SET DASHES routines, a subsequent call to 
DEFAULT GC returns the new default graphics context. 


Display Routines 
DEFAULT GC OF SCREEN 


DEFAULT GC OF SCREEN 


Returns the default graphics context of the specified screen. 





VAX FORMAT —  gc_return =X$DEFAULT_GC_OF_SCREEN 
(screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
ge_return identifier uns longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT = gc_return =XDefaultGCOfScreen 
(screen_id) 





argument 

information GC XDefaultGCOfScreen (screen_id) 
Screen *screen_id; 

RETURNS gc_return 


The identifier of the default graphics context of the specified screen. 





ARGUMENTS __ screen_id 
The identifier of the screen for which the default graphics context is 
requested. 





DESCRIPTION DEFAULT GC OF SCREEN returns the default graphics context of the 
specified screen. 


Display Routines 
DEFAULT ROOT WINDOW 


DEFAULT ROOT WINDOW 


Returns the default root window for a specified display. 





VAX FORMAT _ window_id_return = X$DEFAULT_ROOT_WINDOW 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
window_id_return identifier uns longword write value 
display identifier uns longword read reference 





MIT C FORMAT window_id_return = XDefaultRootWindow 





(display) 
argument 
information Window XDefaultRootWindow (display) 
Display *display; 
RETURNS window _id_return 


The identifier of the root window. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION DEFAULT ROOT WINDOW returns the identifier of the default root 
window for a specified display. 


Display Routines 
DEFAULT SCREEN 


DEFAULT SCREEN 


Returns the default screen referenced in OPEN DISPLAY. 





VAX FORMAT _— screen_number_return = X$DEFAULT_SCREEN 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
screen_number_return identifier uns longword write value 
display identifier uns longword read reference 





MIT C FORMAT = screen_number_return = XDefaultScreen 





(display) 
argument 
information int XDefaultScreen (display) 
Display *display; 
RETURNS screen number return 


The identifier of the default screen referenced in OPEN DISPLAY. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION DEFAULT SCREEN returns the identifier for the default screen referenced 
in the OPEN DISPLAY routine. 


Display Routines 
DEFAULT SCREEN OF DISPLAY 


DEFAULT SCREEN OF DISPLAY 


Returns the default screen of the specified display. 





VAX FORMAT _ screen_id_return= 
X$DEFAULT_SCREEN_OF_DISPLAY 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
screen_id_return record x$screen write value 
display identifier uns longword read reference 





MITC FORMAT -sscreen_id_return = XDefaultScreenOfDisplay 





(display) 
argument 
information Screen *XDefaultScreenOfDisplay (display) 
Display *display; 
RETURNS screen_id_return 


The identifier of the default screen for the specified display. 





ARGUMENTS _ display 
The display information originally returned by the OPEN DISPLAY 
routine. 





DESCRIPTION DEFAULT SCREEN OF DISPLAY returns the default screen of the 
specified display. 


Display Routines 
DEFAULT VISUAL 


DEFAULT VISUAL 


Returns a visual structure for the specified screen. 





VAX FORMAT _ status_return = X$DEFAULT_VISUAL 
(display, screen_number, visual_return) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return cond_value uns longword write value 
display identifier uns longword read reference 
screen_number — uns longword uns longword read reference 
visual_return record x$visual write reference 





MIT C FORMAT visual_return = XDefaultVisual 
(display, screen_number) 





argument 

information Visual *XDefaultVisual (display, screen_number) 
Display *display; 
int screen_number; 

RETURNS status_return (VAX only) 


Specifies whether the routine completed successfully. 


visual_return (MIT C only) 


The returned visual structure. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which you are requesting the visual 
structure. 


visual_return (VAX only) 


The returned visual structure. 





DESCRIPTION DEFAULT VISUAL returns the default visual structure for the specified 
screen. 
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Display Routines 
DEFAULT VISUAL OF SCREEN 


DEFAULT VISUAL OF SCREEN 


Returns the default visual of the specified screen. 





VAX FORMAT X$DEFAULT_VISUAL_OF SCREEN 
(screen_id, visual_return) 


argument 


information Argument | Usage —=—~Data Type ++ Access =—“ Mechanism __ 


screen_id identifier uns longword read reference 
visual_return record x$visual write reference 





MIT C FORMAT visual_return = XDefaultVisualOfScreen 
(screen_id) 





argument 

information Visual *XDefaultVisualOfScreen (screen_id) 
Screen *screen_id; 

RETURNS visual_return (MIT C only) 


The default visual structure for the specified screen. 





ARGUMENTS __ screen id 


The identifier of the screen for which the default visual is requested. 


visual_return (VAX only) 


The returned visual structure. 





DESCRIPTION DEFAULT VISUAL OF SCREEN returns the default visual structure of 
the specified screen. 


Display Routines 
DISPLAY CELLS 


DISPLAY CELLS 


Returns the number of color map cells on the specified screen. 





VAX FORMAT _ cells_return = X$DISPLAY_CELLS 
(display, screen_number) 


argument 


information Argument Usage —-‘Dataype + —«Access_~=—=—s Mechanism _ 


cells_return longword longword write value 
display identifier uns longword read reference 
screen_number — uns longword uns longword read reference 





MITC FORMAT cells_return = XDisplayCells 
(display, screen_number) 





argument 

information int XDisplayCells(display, screen_number) 
Display *display; 
int screen_number; 

RETURNS cells_return 


The number of color map cells on the specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which the number of cells is to be 
determined. 





DESCRIPTION DISPLAY CELLS returns the number of color map cells present on the 
specified screen. 


Display Routines 
DISPLAY HEIGHT 


DISPLAY HEIGHT 


Returns a number that specifies the height of the screen in pixels. 





VAX FORMAT _height_return = X$DISPLAY_HEIGHT 
(display, screen_number) 


argument 


information Argument Usage Data Type Access Machaniam 


height_return uns longword uns longword write value 
display identifier uns longword read reference 
screen_number — uns longword uns longword read reference 





MIT C FORMAT = height_return = XDisplayHeight 
(display, screen_number) 





argument 

information int XDisplayHeight (display, screen_number) 
Display *display; 
int screen_number; 

RETURNS height_return 


The height, in pixels, of the specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which the height is to be obtained. 





DESCRIPTION _ DISPLAY HEIGHT returns an integer that specifies the height, in pixels, 
of the specified screen. 


When you want to obtain the height of a screen in millimeters, use 
DISPLAY HEIGHT MM. 


Display Routines 
DISPLAY HEIGHT MM 


DISPLAY HEIGHT MM 


Returns a number that specifies the height of the screen in millimeters. 





VAX FORMAT __height_return = X$DISPLAY_HEIGHT_MM 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
height_return uns longword uns longword write value 
display identifier uns longword read reference 
screen_number — uns longword uns longword read reference 





MIT C FORMAT = height_return = XDisplayHeightMM 
(display, screen_number) 





argument 

information int XDisplayHeightMM(display, screen_number) 
Display *display; 
int screen_number; 

RETURNS height_return 


The height, in millimeters, of the specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which the height is to be obtained. — 





DESCRIPTION DISPLAY HEIGHT MM returns an integer that specifies the height, in 
millimeters, of the specified screen. 


When you want to obtain the height of a screen in pixels, use DISPLAY 
HEIGHT. 


Display Routines 
DISPLAY NAME 


DISPLAY NAME 


Returns the name of the display that you were trying to open. 





VAX FORMAT _ siatus = X$DISPLAY_NAME 
(disp_string, disp_name_return [,disp_len_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
status cond_value uns longword write value 
disp_string char string char string read descriptor 
disp_name_return char string char string write descriptor 
disp_len_return longword uns longword write reference 





MIT C FORMAT char = XDisplayName 
(disp_string) 


argument 
information char *XDisplayName(disp_string) 
char *string; 





RETURNS status (VAX only) 


Specifies whether or not the routine completed successfully. 


char (MIT C only) 
The name of the display that you are currently using is returned to this 
argument. 





ARGUMENTS _ disp_string 
The name of the display that you are trying to open. If you specify a null 
string, DISPLAY NAME looks in the environment for the display and 
returns the name of the display that OPEN DISPLAY would attempt to 
use. 


VAX only 


The string argument is the address of a character string descriptor that 
points to the string. 


MIT C only 


The string argument is a pointer to the null-terminated character string. 
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Display Routines 


DISPLAY NAME 


disp_name_return (VAX only) 
The address of a character string descriptor that points to the string. 
DISPLAY NAME returns the display name to this argument. 


disp_len_return (VAX only) 
DISPLAY NAME returns the length of the display name string to this 
optional argument. 





DESCRIPTION 
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DISPLAY NAME returns the name of the display that you were trying 

to open. Errors are usually reported relative to a display. If your client 
program fails in an attempt to open a connection to a display, you can use 
DISPLAY NAME to find out the name of the display. 


Display Routines 
DISPLAY OF SCREEN 


DISPLAY OF SCREEN 


Returns the display of the specified screen. 





VAX FORMAT X$DISPLAY_OF_SCREEN 
(screen_id, display_return) 


argument 

information Argument Usage Data Type Access Mechanism 
screen_id identifier uns longword read reference 
display_return record x$display write value 





MIT CFORMAT display_return = XDisplayOfScreen 
(screen_id) 





argument 

information Display *XDisplayOfScreen (screen_id) 
Screen *screen_id; 

RETURNS display_return (MIT C only) 


The display of the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the value is requested. 


display_return (VAX only) 
The display of the specified screen. 





DESCRIPTION _ DISPLAY OF SCREEN returns the display of the specified screen. 


Display Routines 
DISPLAY PLANES 


DISPLAY PLANES 


Returns the number of planes on the specified screen. 





VAX FORMAT _ planes_return = X$DISPLAY_PLANES 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
planes_return longword longword write value 
display identifier uns longword read reference 
screen_number — uns longword uns longword read reference 





MIT C FORMAT planes_return = XDisplayPlanes 
(display, screen_number) 





argument 

information int XDisplayPlanes (display, screen_number) 
Display *display; 
int screen number; 

RETURNS planes_return 


The number of planes on the specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which you want to obtain the number of 
planes. 





DESCRIPTION _ DISPLAY PLANES returns the number of planes on the specified screen. 


Display Routines 
DISPLAY STRING 


DISPLAY STRING 


Returns the name of the string that was passed to OPEN DISPLAY when the 
current display was opened. 





VAX FORMAT _ siatus_return = X$DISPLAY_STRING 
(display, name_return [,len_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return cond_value uns longword write value 
display identifier uns langword read reference 
name_return char string char string write descriptor 
len_return unsigned_word uns word write reference 





MIT C FORMAT | siatus_return = XDisplaySiring 





(display) 
argument 
information char *XDisplayString (display) 
Display *display; 
RETURNS status_return 


Specifies whether the routine completed successfully. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


name_return (VAX only) 
The name of the string that was passed to OPEN DISPLAY when the 
current display was opened. 


The name_return argument is the address of a character string 
descriptor that points to the string. 


len_return (VAX only) 
The length of the returned string. This argument is optional. 
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Display Routines 
DISPLAY STRING 





DESCRIPTION DISPLAY STRING returns the name of the string that was passed to 
OPEN DISPLAY when the current hardware display was opened. If the 
string was null, DISPLAY STRING returns the value of the logical name 
when the current display was opened. 


DISPLAY STRING is useful to applications that want to open a new 
connection from the child process to the same hardware display. 
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Display Routines 
DISPLAY WIDTH 


DISPLAY WIDTH 


Returns a number that specifies the width of the screen in pixels. 





VAX FORMAT _ width_return = X$DISPLAY_WIDTH 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
width_return uns longword uns longword write value 
display identifier uns longword read reference 
screen_number — uns longword uns longword read reference 





MIT C FORMAT width_return = XDisplayWidth 
(display, screen_number) 





argument 

information int XDisplayWidth (display, screen_number) 
Display *display; 
int screen_number; 

RETURNS width_return 


The width, in pixels, of the specified screen. 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for the width is to be obtained. 





DESCRIPTION DISPLAY WIDTH returns an integer that specifies the width, in pixels, of 
the specified screen. 


When you want to obtain the width of a screen in millimeters, use 
DISPLAY WIDTH MM. 


Display Routines 
DISPLAY WIDTH MM 


DISPLAY WIDTH MM 


Returns a number that specifies the width of the screen in millimeters. 





VAX FORMAT _~ width_return = X$DISPLAY_WIDTH_MM 
(display, screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
width_return uns longword uns longword write value 
display identifier uns longword read reference 
screen_id identifier uns longword read reference 





MIT CFORMAT  width_return = XDisplayWidthMM 
(display, screen_id) 





argument 

information int XDisplayWidthMM(display, screen_id) 
Display *display; 
int screen_id; 

RETURNS width_return 


The width, in millimeters, of the specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_id 
The identifier of the screen for which the width is to be obtained. 





DESCRIPTION _ DISPLAY WIDTH MM returns an integer that specifies the width, in 
millimeters, of the specified screen. 


When you want to obtain the width of a screen in pixels, use DISPLAY 
WIDTH. 


Display Routines 
DOES BACKING STORE 


DOES BACKING STORE 


Returns a value that indicates whether the screen supports backing stores. 





VAX FORMAT _ support_value = X$DOES_BACKING_STORE 
(screen_id) 


argument 


information Argument Usage —~—-‘DataType === Access. ~=—S—S—s«s Mechanism 


support_value — longword longword write value 
screen_id identifier uns longword __ read reference 





MIT C FORMAT _ support_value = XDoesBackingStore 
(screen_id) 





argument 

information ret XDoesBackingStore (screen_id) 
Screen *screen_id; 

RETURNS support_value 


A value that indicates whether the screen supports backing stores. This 
can be one of the following values: 


VAX Cc Description 
X$C_ALWAYS Always The server always maintains the contents 


of obscured window regions. 


X$C_WHEN_MAPPED  WhenMapped _ The server maintains the contents of 
obscured window regions when the 
window is mapped. 

X$C_NOT_USEFUL NoiUseful The server does not maintain the contents 
of obscured window regions. 





ARGUMENTS _ screen_id 


The identifier of the screen for which the value is requested. 





DESCRIPTION DOES BACKING STORE returns a value that indicates whether the 
screen supports backing stores. 
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Display Routines 
DOES SAVE UNDERS 


DOES SAVE UNDERS 


Returns a Boolean value that indicates whether the screen supports save 
unders. 





VAX FORMAT _ Bool =X$DOES SAVE _UNDERS (screen_id) 


argument 


information Argument Usage | —~DataType Access ==—‘ Mechanism _ 


Bool Boolean uns longword write value 
screen_id identifier uns longword read reference 





MITC FORMAT Bool=XDoesSaveUnders (screen_id) 





argument 

information ret xDoesSaveUnders (screen_id) 
Screen *screen_id; 

RETURNS Bool 


A Boolean value that, when true, indicates that the screen supports save 
unders. If this value is false, the screen does not support save unders. 





ARGUMENTS __ screen id 


The identifier of the screen for which the value is requested. 





DESCRIPTION DOES SAVE UNDERS indicates whether the screen supports save unders. 


Display Routines 
EVENT MASK OF SCREEN 


EVENT MASK OF SCREEN 


Returns the initial root event mask of the specified screen. 





VAX FORMAT = mask_return = X$EVENT_MASK_OF_SCREEN 
(screen_id) 


argument 


information Argument Usage —‘Data Type += Access.-~=—S—s=«é« Mechanism 


mask_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT mask_return =XEventMaskOfScreen 
(screen_id) 





argument 

information long XEventMaskOfScreen (screen_id) 
Screen *screen_id; 

RETURNS mask_return 


The initial root event mask of the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the event mask is requested. 





DESCRIPTION EVENT MASK OF SCREEN returns the initial root event mask of the 
specified screen. 


Display Routines 
FREE 


FREE 


Frees a data buffer that was created by an Xlib routine. 





VAXFORMAT X$FREE (buff_pir [,buff_len)) 


argument 

information Argument Usage Data Type Access Mechanism 
buff_ptr byte v. uns byte read reference 
buff_len longword longword read reference 





C FORMAT XFree (buff _ptr) 


argument 


. . XxFree (buff ptr) 
information char *buff ptr 





ARGUMENTS _ buff_pir 


A pointer to the data buffer that is to be freed. 


buff_len (MIT C Only) 


The size, in bytes, of the buffer. This argument is optional; if it is not 
specified, buff_ptr is assumed to contain a null-terminated byte stream. 





DESCRIPTION _ FREE frees a data buffer that was created by an Xlib routine. 
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Display Routines 
HEIGHT MM OF SCREEN 


HEIGHT MM OF SCREEN 


Returns the height, in millimeters, of the specified screen. 





VAX FORMAT __height_return = X$HEIGHT_MM_OF_SCREEN 
(screen_id) 


argument 


information Argument Usage —~Data Type == Access. ~=—S——s« Mechanism 


height_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT height_return = XHeightMMOfScreen 
(screen_id) 





argument 

information int XHeightMMOfScreen(screen_id) 
Screen *screen_id; 

RETURNS height_return 


The height, in millimeters, of the specified screen. 





ARGUMENTS __screen_id 
The identifier of the screen for which the height is requested. 





DESCRIPTION HEIGHT MM OF SCREEN returns the height, in millimeters, of the 
specified screen. 


When you want to obtain the height of a screen in pixels, use HEIGHT OF 
SCREEN. 
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Display Routines 
HEIGHT OF SCREEN 


HEIGHT OF SCREEN 


Returns the height, in pixels, of the specified screen. 





VAX FORMAT __height_return = X$HEIGHT_OF_SCREEN 
(screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
height_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT _height_return = XHeightOfScreen 
(screen_id) 





argument 

information int XHeightOfScreen (screen_id) 
Screen *screen_id; 

RETURNS height_return 


The height, in pixels, of the specified screen. 





ARGUMENTS __ screen _id 


The identifier of the screen for which the height is requested. 





DESCRIPTION HEIGHT OF SCREEN returns the height, in pixels, of the specified screen. 


When you want to obtain the height of a screen in millimeters, use 
HEIGHT MM OF SCREEN. 
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Display Routines 
IMAGE BYTE ORDER 


IMAGE BYTE ORDER 


The required byte order for images for each scan line unit in XYFormat 
(bitmap) or for each pixel value in ZFormat. 





VAX FORMAT _ order_return = X$IMAGE_BYTE_ORDER 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
order_return longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT order_return = XimageByteOrder 





(display) 
argument 
information int XImageByteOrder (display) 
Display *display; 
RETURNS order_return 


The byte order for images for each scan line unit in XYFormat (bitmap) or 
for each pixel value in ZFormat. IMAGE BYTE ORDER returns one of the 
following constants: 


VAX Cc Description 
X$C_LSB_FIRST LSBFirst Least significant bit first 
X$C_MSB_FIRST MSBFirst Most significant bit first 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION IMAGE BYTE ORDER specifies the required byte order for images for 
each scan line unit in XYFormat (bitmap) or for each pixel value in 
Z¥Format. IMAGE BYTE ORDER returns a value of either least significant 
byte first or most significant byte first. 
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Display Routines 
LAST KNOWN REQUEST PROCESSED 


LAST KNOWN REQUEST PROCESSED 


Extracts the serial number of the last request known by Xlib to have been 
processed to the X server. 





VAX FORMAT __ request_return = 
X$LAST_KNOWN_REQUEST_PROCESSED 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
request_return uns longword uns longword write value 
display identifier uns longword read reference 





MIT C FORMAT = request_return = XLastKnownRequestProcessed 





(display) 
argument 
information int XLastKnownRequestProcessed (display) 
Display *display; 
RETURNS request_return 


The serial number of the last request known by Xlib to have been 
processed to the X server. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION LAST KNOWN REQUEST PROCESSED extracts the serial number of the 
last request known by Xlib to have been processed to the X server. This 
number is automatically set by Xlib when replies, events, and errors are 
received. 


Display Routines 
MAX CMAPS OF SCREEN 


MAX CMAPS OF SCREEN 


Returns the maximum number of installed color maps supported by the 
specified screen. 





VAX FORMAT _ colormaps_return = X$MAX_CMAPS_OF_SCREEN 
(screen_id) 


argument 


information Argument —~—- Usage ~=—sdData Type Access Mechanism —__ 


colormaps_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT colormaps_return = XMaxCmapsOfScreen 
(screen_id) 





argument 

information int XMaxCmapsOfScreen(screen_id) 
Screen *screen_id; 

RETURNS colormaps_return 


The maximum number of installed color maps supported by the specified 
screen, 





ARGUMENTS __ screen_id 
The identifier of the screen for which the number of colormaps is 
requested. 





DESCRIPTION MAX CMAPS OF SCREEN returns the maximum number of installed 
color maps supported by the specified screen. 
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MIN CMAPS OF SCREEN 


Returns the minimum number of installed color maps supported by the 
specified screen. 





VAX FORMAT _ colormaps_return = X$MIN_CMAPS_OF_SCREEN 
(screen_id) 


argument 


information Argument +~—~—«*Usage.+~=—-—=Ss@Data Type ~~ Access += Mechanism __ 


colormaps_return longword longword write value 
screen_id identifier uns longword read reference 





MITC FORMAT colormaps_return = XMinCmapsOfScreen 
(screen_id) 





argument 

information int XMinCmapsOfScreen (screen_id) 
Screen *screen_id; 

RETURNS colormaps_return 


The minimum number of installed color maps supported by the specified 
screen. 





ARGUMENTS __ screen_id 
The identifier of the screen for which the number of colormaps is 
requested. 





DESCRIPTION MIN CMAPS OF SCREEN returns the minimum number of installed color 
maps supported by the specified screen. 
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NEXT REQUEST 


Extracts the serial number that is to be used for the next request. 





VAX FORMAT __ request_return = X$NEXT_REQUEST (display) 


argument 

information Argument Usage Data Type Access Mechanism 
request_return uns longword uns longword write value 
display identifier uns longword read reference 





MIT C FORMAT request_return = XNextRequest (alsplay) 





argument 

information int XNextRequest (display) 
Display *display; 

RETURNS request_return 


The serial number that Xlib is to use for the next request. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION NEXT REQUEST extracts the serial number that is to be used for the 
next request. Serial numbers are maintained separately for each display 
connection. 
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NO OP 


Sends a no-operation protocol request to the server. 





VAXFORMAT X$NO_OP (display) 


argument 


information Argument Usage —-‘DataType === Access_~=—S Mechanism _ 


display identifier uns longword read reference 





MITC FORMAT XNoOp (display) 


argument 


information XNoOp (display) 
Display *display; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION NO OP generates a no-operation server protocol request. It does not 
explicitly flush the output buffer. 
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OPEN DISPLAY 


Opens a connection between a client program and the display that you 
specify. 





VAX FORMAT _ display_return = X$OPEN_DISPLAY 
(display_name) 


argument 

information Argument Usage Data Type Access Mechanism 
display_return identifier uns longword write value 
display_name char string char string read descriptor 





MIT C FORMAT display_return = XOpenDisplay 
(display_name) 





argument 
information Display *XOpenDisplay (display name) 
char *display name; 
RETURNS display_return 
An identifier that uniquely identifies the connection to the display that you 
opened. 





ARGUMENTS _~ display_name 


The name of the hardware display to which you want to connect. The 
display_name argument is a string that has the following format: 


hostname: :number.screen. 
The string elements are as follows: 


hostname The name of the host machine to which the display is physically 
connected. Specify 0 if the client program and the server are running 
in the same CPU. 


number The number of the server on that host machine. A single CPU can 
have more than one server, which are usually numbered starting with 
zero. 
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OPEN DISPLAY 


screen The number of the screen on that server. An X server can control 
multiple screens on one display. The screen sets an internal variable 
that can be accessed by using the DefaultScreen macro or the 
DEFAULT SCREEN function. 


VAX only 


The display_name argument is the address of the character string 
descriptor that points to the string. 


C only 


The display_name argument is a pointer to a null-terminated character 
string. 





DESCRIPTION 
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OPEN DISPLAY connects a client program to the specified display. You 
pass to OPEN DISPLAY the name of the display to which you want to 
connect. If successful, OPEN DISPLAY establishes the connection to the 
display and returns a pointer to a display identifier. If OPEN DISPLAY 
does not succeed, it returns a null value in the MIT C binding and a zero 
in the VAX binding. 


After you successfully connect the client to the display, you can obtain data 
from the display using other Xlib routines. However, OPEN DISPLAY 
should be called before calling any other Xlib routines. 


Display Routines 
PLANES OF SCREEN 


PLANES OF SCREEN 


Returns the number of planes in the specified screen. 





VAX FORMAT _ planes_return = X$PLANES_OF_SCREEN 
(screen_id) 


argument 


information Argument Usage —-‘Data Type Access. == Mechanism _ 


planes_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT planes_return = XPlanesOfScreen 
(screen_id) 





argument 

information int XPlanesOfScreen(screen_id) 
Screen *screen_id; 

RETURNS planes_return 


The number of planes in the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen 





DESCRIPTION PLANES OF SCREEN returns the number of planes in the specified 


screen. 


Display Routines 
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PROTOCOL REVISION 


Returns the minor protocol revision number that the X server is using. 





VAX FORMAT __ revision_return = X$PROTOCOL_REVISION 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
revision_return longword longword write value 
display identifier uns longword read reference 





MITC FORMAT revision_return = XProtocolRevision 





(display) 
argument 
information int XProtocolRevision (display) 
Display *display; 
RETURNS revision_return 


The minor protocol revision number that the X server is using. 





ARGUMENTS _~ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION PROTOCOL REVISION returns the minor protocol revision number that 
the X server is using. 
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PROTOCOL VERSION 


Returns the version number of the X protocol associated with the connected 
display. 





VAX FORMAT _. version_return = X$PROTOCOL_VERSION 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
version_return longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT _sversion_return = XProtocolVersion 





(display) 
argument 
information int XProtocolVersion (display) 
Display *display; 
RETURNS version_return 


The version number of the X protocol associated with the connected 
hardware display. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION PROTOCOL VERSION returns the version number of the X protocol 
associated with the connected display. 
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Q LENGTH 


Returns the length of the input event queue for the connected hardware 
display. 





VAX FORMAT __length_return =X$Q_LENGTH (display) 


argument 

information Argument Usage Data Type Access Mechanism 
length_return longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT /ength_return=XQLength (display) 





argument 

information int XQLength (display) 
Display *display; 

RETURNS length_return 


The length of the input event queue for the connected hardware display. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION Q LENGTH returns the length of the input event queue for the connected 
hardware display. See also the EVENTS QUEUED routine. 
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ROOT WINDOW 


Returns the identifier of the root window. 





VAX FORMAT __ root_window_id_return = X$ROOT_WINDOW 
(display, screen_number) 


argument 

information Argument Usage Data Type Access Mechanism 
root_window_id_return identifier uns longword write value 
display identifier uns longword read reference 
screen_number uns longword uns longword read reference 





MIT C FORMAT = root_window_id_return = XRootWindow 
(display, screen_number) 





argument 

information Window XRootWindow(display, screen_number) 
Display *display; 
int screen_number; 

RETURNS root_window_id_return 


The identifier of the root window. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_number 
The number of the screen for which the root window is to be obtained. 





DESCRIPTION ROOT WINDOW obtains the identifier of the root window. ROOT 
WINDOW is useful with other Xlib routines that take a parent window 
as an argument. 


Display Routines 
ROOT WINDOW OF SCREEN 


ROOT WINDOW OF SCREEN 


Returns the root window of the specified screen. 





VAX FORMAT _— window_id_return =X$ROOT_WINDOW_OF_SCREEN 
(screen_id) 


argument 


information Argument —*Usage_~—=S@Data Type +=» Access. Mechanism 


window_id_return identifier uns longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT window_id_return =XRootWindowOfScreen 
(screen_id) 





argument 

information Window XRootWindowOfScreen (screen_id) 
Screen *screen_id; 

RETURNS window_id_return 


The identifier of root window of the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the root window is requested. 





DESCRIPTION ROOT WINDOW OF SCREEN returns the root window of the specified 


screen. 


Display Routines 
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ROTATE BUFFERS 


Rotates the ring of cut buffers from 0 to 7. 





VAX FORMAT X$ROTATE_BUFFERS (display, rotate) 


argument 


information Argument Usage ——iData Type =—Access_~=—s Mechanism 


display identifier uns longword read reference 
rotate longword longword read reference 





MITC FORMAT XRotateBuffers (display, rotate) 


argument 

information XRotateBuffers (display, rotate) 
Display *display; 
int rotate; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


rotate 
Specifies how much to rotate the cut buffers. 





DESCRIPTION ROTATE BUFFERS rotates the cut buffers based on the value that you 
specify. Buffer 0 becomes buffer n, buffer 1 becomes buffer n+1 MOD 8, 
and so on. This method of numbering cut buffers is global to the display. 
Note that ROTATE BUFFERS generates an error if any of the eight 
buffers have not been created. 


Display Routines 
ROTATE BUFFERS 





X ERRORS 
VAX Cc Description 
X$C_BAD_ATOM BadAtom The value that you specified in an atom 
argument does not name a defined atom. 
X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined 
window. 
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SCREEN COUNT 


Returns the number of screens in the specified display. 





VAX FORMAT _ count_return = X$SCREEN_COUNT (display) 


argument 

information Argument Usage Data Type Access Mechanism 
count_return longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT count_return=XScreenCount (display) 





argument 

information int XScreenCount (display) 
Display *display; 

RETURNS request_return 


The number of screens in the specified display. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION ‘SCREEN COUNT returns the number of screens in the specified display. 
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SCREEN OF DISPLAY 


Returns the identifier of the screen of the specified display. 





VAX FORMAT X$SCREEN_OF_DISPLAY 
(display, screen_number, screen_return) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
screen_number uns longword uns longword read reference 
screen_return record x$screen write reference 





MITC FORMAT = screen_id_return =XScreenOfDisplay 
(display, screen_number) 





argument 

information Screen *XScreenOfDisplay (display, screen_number) 
Display *display; 
int screen number; 

RETURNS screen_id_return (MIT C only) 


The identifier of the screen associated with the specified display. 





ARGUMENTS __ display 
The display information originally returned by the OPEN DISPLAY 
routine. 


screen_number 
The number of the returned screen. 


screen_return (VAX only) 
The identifier of the screen associated with the specified display. 





DESCRIPTION SCREEN OF DISPLAY returns the identifier of the screen associated with 
the specified display. 
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SERVER VENDOR 


Returns a pointer to a string that identifies the owner of the X server 
implementation. 





VAX FORMAT X$SERVER_VENDOR 
(display, vendor_name_return, [len_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
string_name char string char string read descriptor 
display identifier uns longword read reference 
vendor_name_return char string char_string write descriptor 
len_return word uns word write reference 





MIT C FORMAT vendor_name_return = XServerVendor 





(display) 
argument 
information char *XServerVendor (display) 
Display *display; 
RETURNS vendor_name_return (MIT C only) 
The name of the string that identifies the owner of the X server 
implementation. 


The vendor_name_return argument is a pointer to the null-terminated 
character string. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


vendor_name_return (VAX only) 
The name of the string that identifies the owner of the X server 
implementation. 


The vendor_name_return argument is the address of a character string 
descriptor that points to the string. 


len_return (VAX only) 
The length of the returned string. This argument is optional. 
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DESCRIPTION SERVER VENDOR returns a pointer to a character string that identifies 
the owner of the X server implementation. 
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STORE BUFFER 


Stores data in a specified cut buffer. 





VAX FORMAT X$STORE_BUFFER 
(display, bytes, num_bytes, buffer) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
byies array byte read reference 
num_bytes longword longword read reference 
buffer longword longword read reference 





MITC FORMAT XStoreBuffer 
(display, bytes, num_bytes, buffer) 


argument 

information XStoreBuffer (display, bytes, num_bytes, buffer) 
Display *display; 
char bytes[]; 


int num_bytes; 
int buffer; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


bytes 

A pointer to the array of bytes that you want to store. The length of the 
array is specified by num_bytes. The byte string is not necessarily ASCII 
or null terminated. 


num_bytes 
The number of bytes that you want to store in the bytes argument. 


buffer 
The buffer in which you want to store the byte string. Valid entries are 0 
through 7. 





DESCRIPTION STORE BUFFER stores the string of bytes in the buffer that you specify. 
Clients can retrieve the contents of the cut buffer by calling FETCH 
BUFFER. 
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X ERRORS 
VAX c Description 
X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 
resource for any cause. 
X$C_BAD_ATOM BadAtom The value that you specified in an atom 


argument does not name a defined atom. 


X$C_BAD_WINDOW ~~ BadWindow __ A value that you specified for a window 
argument does not name a defined window. 
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STORE BYTES 


Stores data in cut buffer zero. 





VAX FORMAT X$STORE_BYTES 
(display, bytes, num_bytes) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
bytes array byte read reference 
num_bytes longword longword write reference 





MITC FORMAT XStoreBytes 
(display, bytes, num_bytes) 


argument 

information XStoreBytes (display, bytes, num_bytes) 
Display *display; 
char bytes[]; 


int num_bytes; 





ARGUMENTS ~ display 
The display information originally returned by OPEN DISPLAY. 


bytes 

A pointer to the array of bytes that you want to store. The byte string is 
not necessarily ASCII text or a null-terminated string. The length of the 
array is specified by num_bytes. 


num_bytes 
The number of bytes in the string that you want to store. 





DESCRIPTION STORE BYTES returns the number of bytes to be stored to the 
num_bytes argument. 


Clients can retrieve the contents of the cut buffer by calling FETCH 
BYTES. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 
resource for any cause. 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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VENDOR RELEASE 


Returns the number of the release of the X server, as assigned by the vendor. 





VAX FORMAT __ release_return = X$VENDOR_RELEASE 


(display) 
argument 
information Argument Usage Data Type Access Mechanism 
release_return longword longword write value 
display identifier uns longword read reference 





MIT C FORMAT re/ease_return = XVendorRelease 





(display) 
argument 
information int XVendorRelease (display) 
Display *display; 
RETURNS release_return 


The number of the release of the X server, as assigned by the vendor. 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION VENDOR RELEASE returns the number of the release of the X server, as 
assigned by the vendor. 


Display Routines 
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WHITE PIXEL 


Returns the color index (pixel value) that yields white on the specified screen. 





VAX FORMAT _ color_index_return = X$WHITE_PIXEL 
(display, screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
color_index_return identifier uns longword write value 
display identifier uns longword read reference 
screen_id identifier uns longword read reference 





MITC FORMAT  color_index_return = XWhitePixel 
(display, screen_id) 





argument 

information unsigned long XWhitePixel (display, screen_id) 
Display *display; 
int screen_id; 

RETURNS color_index_return 


The identifier of the color index (pixel value) that yields white on the 
specified screen. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


screen_id 
The identifier of the screen for which the white pixel is requested. 





DESCRIPTION WHITE PIXEL returns the color index (pixel value) that yields white on 
the specified screen. 


To obtain the color index that yields black on the specified screen, use 
BLACK PIXEL. 


Display Routines 
WHITE PIXEL OF SCREEN 


WHITE PIXEL OF SCREEN 


Returns the white pixel of the specified screen. 





VAX FORMAT _ color_index_return = X$WHITE_PIXEL_OF_SCREEN 
(screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
color_index_return identifier uns longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT color_index_return = XWhitePixelOfScreen 
(screen_id) 





argument 

information unsigned long XWhitePixelOfScreen(screen_id) 
Screen *screen_id; 

RETURNS color_index_return 


The identifier of the color index (pixel value) that yields white on the 
specified screen. 





ARGUMENTS __ screen id 


The identifier of the screen for which the white pixel is requested. 





DESCRIPTION WHITE PIXEL OF SCREEN returns the white pixel of the specified 


screen. 


To obtain the black pixel of the specified screen, use BLACK PIXEL OF 
SCREEN. 
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WIDTH MM OF SCREEN 


Returns the width, in millimeters, of the specified screen. 





VAX FORMAT _ width_return =X$WIDTH_MM_OF_SCREEN 
(screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
width_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT width_return = XWidthMMOfScreen 
(screen_id) 





argument 

information width XWidthMMOfScreen (screen_id) 
Screen *screen_id; 

RETURNS width_return 


The width, in millimeters, of the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the width is requested. 





DESCRIPTION WIDTH MM OF SCREEN returns the width, in millimeters, of the 
specified screen. 


When you want to obtain the width of a screen in pixels, use WIDTH OF 
SCREEN. 


Display Routines 
WIDTH OF SCREEN 


WIDTH OF SCREEN 


Returns the width, in pixels, of the specified screen. 





VAX FORMAT ~ width_return = X$WIDTH_OF_SCREEN 
(screen_id) 


argument 

information Argument Usage Data Type Access Mechanism 
width_return longword longword write value 
screen_id identifier uns longword read reference 





MIT C FORMAT width_return = XWidthOfScreen 
(screen_id) 





argument 

information long XWidthOfScreen(screen_id) 
Screen *screen_id; 

RETURNS width_return 


The width, in pixels, of the specified screen. 





ARGUMENTS __ screen_id 


The identifier of the screen for which the width is requested. 





DESCRIPTION WIDTH OF SCREEN returns the width, in pixels, of the specified screen. 


When you want to obtain the width of a screen in millimeters, use WIDTH 
MM OF SCREEN. 
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Window Routines 


The Xlib window routines enable you to perform the following operations: 


e Create windows 

¢ Destroy windows 

¢ Map windows 

¢ Unmap windows 

¢ Configure windows 

¢ Raise and lower windows 


¢ Change window attributes 


¢ Provide window information 


¢ Translate window coordinates 


For concepts related to window routines and information on how to use 
window routines, see the VMS DECwindows Xlib Programming Volume. 


The routines described in this chapter are listed in Table 3-1. 


Table 3-1 Window Routines 


Routine Name 


CHANGE WINDOW ATTRIBUTES 
CIRCULATE SUBWINDOWS 


CIRCULATE SUBWINDOWS DOWN 


CIRCULATE SUBWINDOWS UP 


CONFIGURE WINDOW 


CREATE SIMPLE WINDOW 


CREATE WINDOW 


DESTROY SUBWINDOWS 
DESTROY WINDOW 


GET GEOMETRY 


Description 


Sets the atiriputes of a specified window. 


Circulates the appropriate child of a window in 
a specified direction. 


Lowers the highest mapped child window of a 
window that occludes another window. 


Raises the lowest mapped child of an 
occluded window. 


Reconfigures a window’s size, position, border, 
and stacking order. 


Creates a subwindow of a specified parent 
window from an application. 


Creates a subwindow of a parent window and 
defines the attributes of the subwindow. 


Destroys ail subwindows of a window. 


Destroys a window and all of its subwindows 
from an application. 


Obtains the current geometry of the specified 
drawable. 


(continued on next page) 
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Table 3-1 (Cont.) Window Routines 


Routine Name 


GET WINDOW ATTRIBUTES 
LOWER WINDOW 


MAP RAISED 


MAP SUBWINDOWS 
MAP WINDOW 


MOVE RESIZE WINDOW 


MOVE WINDOW 


QUERY POINTER 


QUERY TREE 


RAISE WINDOW 


RESIZE WINDOW 
RESTACK WINDOWS 


SET WINDOW BACKGROUND 


SET WINDOW BACKGROUND 
PIXMAP 


SET WINDOW BORDER 
SET WINDOW BORDER PIXMAP 


SET WINDOW BORDER WIDTH 
TRANSLATE COORDINATES 


UNMAP SUBWINDOWS 
UNMAP WINDOW 


Description 


Obtains the attributes of a specified window. 


Lowers a window so that it does not obscure 
any sibling windows. 


Maps the specified window and raises it to the 
top of the stack. 


Maps all subwindows of a specified window. 


Maps a window and all of its subwindows that 
have had map requests. 


Changes the location and the size of a 
specified window. 


Moves and raises a window without changing 
its size. 


Obtains the root window where the pointer is 
currently located and the pointer coordinates 
relative to the root window’s origin. 


Lists the parent, the children, and the number 
of children for a window. 


Raises a window so that no sibling window 
obscures it. 


Changes the size of a window. 


Restacks an array of windows from top to 
bottom. 


Sets the background of a specified window to 
the specified pixel. 


Changes the background tile of a specified 
window. 


Sets a window’s border to a specified pixel. 


Changes and repaints the border tile of a 
specified window. 


Changes the border width of a window. 


Transfers coordinates from the coordinate 
space of one window to another. 


Unmaps all subwindows of a specified window. 
Unmaps a window. 


The routines use the following data structures: 


¢ Set window attributes 
¢ Window changes 
e Window attributes 
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Window Routines 
3.1 Set Window Attributes Data Structure 


Set Window Attributes Data Structure 


The set window attributes data structure specifies and receives 
information about window attributes. The data structure for the VAX 
binding is shown in Figure 3-1, and information about members in the 
data structure is described in Table 3-2. 


Figure 3-1 Set Window Attributes Data Structure (VAX Binding) 













: 
: 
x$l_swda_bit_gravity 16 
: 
x$l_swda_backing_store 24 
: 
: 
: 
: 
“ 
: 
: 
: 
Table 3-2 Members of the Set Window Attributes Data Structure (VAX Binding) 
Member Name Contents 
X$L_SWDA_BACKGROUND_PIXMAP Defines the window background of an input-output window. This 


member can assume one of three possible values: pixmap 
identifier, the constant x$c_none (default), or the constant 
x$c_parent_relative. 


(continued on next page) 
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3.1 Set Window Attributes Data Structure 


Table 3-2 (Cont.) Members of the Set Window Attributes Data Structure (VAX Binding) 


Member Name 


X$L_SWDA_BACKGROUND_ PIXEL 


X$L_SWDA_BORDER_PIXMAP 


X$L_SWDA_BORDER_PIXEL 


X$L_SWDA_BIT_GRAVITY 


X$L_SWDA_WIN_GRAVITY 


X$L_SWDA_BACKING_STORE 


X$L_SWDA_BACKING_PLANES 


X$L_SWDA_BACKING_PIXEL 


X$L_SWDA_SAVE_UNDER 


X$L_SWDA_EVENT_MASK 


X$L_SWDA_DO_NOT_PROPAGATE_MASK 


Contents 


Specifying a value for the X$L_SWDA_BACKGROUND_PIXEL 
member causes the server to override the 
X$L_SWDA_BACKGROUND_PIXMAP member. This is 
equivalent to a specifying pixmap of any size filled with the 
background pixel and used to paint the window background. 


Defines the window border of an input-output window. This 
member can be either X$C_COPY_FROM_PARENT or a 
pixmap identifier. 

Specifying a value for X$L__SWDA_BORDER_PIXEL causes the 
server to override the X$L_SWDA_BORDER_PIXMAP member. 
This is equivalent to specifying a pixmap of any size filled with 
the border pixel and used to paint the window border. 


Defines how window contents should be moved when an input- 
only or input-output window is resized. By default, the server 
does not retain window contents. 


Defines how the server should reposition the newly-created 
input-only or input-output window when its parent window is 
resized. By default, the server does not move the newly created 
window. 


Provides a hint to the server about how the client wants it to 
manage obscured portions of the window. In this release clients 
must maintain window contents. 


Indicates (with bits set to one) which bit planes of the window 
hold dynamic data that must be preserved if the window 
obscures or is obscured by another window. In this release 
clients must maintain data to be preserved. 


Defines what values to use in planes not specified by the 
X$L_SWDA_BACKING_PLANES member. In this release 
clients must maintain values. 


Setting the X$L_SWDA_SAVE_UNDER member to true informs 
the server that the client would like the contents of the screen 
saved when an input-output window obscures them. Clients 
must maintain the contents of screens. 


Defines which types of events associated with an input-only or 
input-output window the server should report to the client. A 
complete table appears in Chapter 4. 


Defines which kinds of events should not be propagated to 
ancestors. 
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Table 3—2 (Cont.) Members of the Set Window Attributes Data Structure (VAX Binding) 


Member Name 


X$L_SWDA_OVERRIDE_REDIRECT 


X$L_SWDA_COLORMAP 


X$L_SWDA_CURSOR 


Contents 


Specifies whether calls to map and configure an input-only or 


input-output window should override a request by another client 
to redirect those calls. Typically, this is used to inform a window 
manager not to tamper with the window, for example when the 
client is creating and mapping a menu. 


Specifies the color map, if any, that best reflects the colors of an 
input-output window. The color map must have the same visual 
type as the window. If it does not, the server issues an error. 


Specifying a value for the cursor member causes the server to 
use a particular cursor when the pointer is in an input-only or 


input-output window. 





Table 3-8 lists default values for the SET WINDOW ATTRIBUTES 


structure. 


Table 3-3 Default Values of the Set Window Attributes Structure 


Member 


X$L_SWDA_BACKGROUND_PIXMAP 
X$L_SWDA_BACKGROUND_PIXEL 


X$L_SWDA_BORDER_PIXMAP 
X$L_SWDA_BORDER_PIXEL 
X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 
X$L_SWDA_BACKING_STORE 
X$L_SWDA_BACKING_PLANES 
X$L_SWDA_BACKING_PIXEL 
X$L_SWDA_SAVE_UNDER 
X$L_SWDA_EVENT_MASK 


X$L_SWDA_DO_NOT_PROPAGATE_MASK 
X$L_SWDA_OVERRIDE_REDIRECT 


X$L_SWDA_COLORMAP 
X$L_SWDA_CURSOR 


Default Value 


None 

Undefined 

Copied from the parent window 
Undefined 

Window contents not retained 
Window not moved 

Window contents not retained 
All 1s 

0 

False 

Empty set 

Empty set 

False 

Copied from parent 

None 


The data structure for the MIT C binding is shown in Figure 3-2, 
and information about members in the data structure is described in 


Table 3-4. 
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Figure 3-2 Set Window Attributes Data Structure (MIT C Binding) 


typedef struct { 
Pixmap background_pixmap; 
unsigned long background _pixel; 
Pixmap border _pixmap; 
unsigned long border_pixel; 
int bit_gravity; 
int win_gravity; 
int backing store; 
unsigned long backing planes; 
unsigned long backing _pixel; 
Bool save_under; 
long event_mask; 
long do_not_ propagate mask; 
Bool override_redirect; 
Colormap colormap; 
Cursor cursor; 

} XSetWindowAttributes 


Table 3-4 Members of the Set Window Attributes Structure (MIT C Binding) 
Member Name Contents 








background_pixmap Defines the window background. The background_pixmap member can 
assume one of three possible values: pixmap identifier, the constant None 
(default), or the constant ParentRelative. 


background_pixel Specifying a value for the background_pixel member causes the server 
to override the background_pixmap member. This is equivalent to a 
specifying pixmap of any size filled with the background pixel and used to 
paint the window background. 


border_pixmap Defines the window border. This can either be CopyFromParent or a 
Pixmap. 
border_pixel Specifying a value for border_pixel causes the server to override the 


border_pixmap member. This is equivalent to specifying a pixmap of any 
size filled with the border pixel and used to paint the window border. 


bit_gravity Defines how the contents of the window should be moved when the 
window is resized. By default, the server does not retain window contents. 
win_gravity Defines how the server should reposition the newly-created window when 


its parent window is resized. By default, the server does not move the 
newly created window. 
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Table 3-4 (Cont.) Members of the Set Window Attributes Structure (MIT C Binding) 


Member Name 


backing_store 


backing_planes 


backing_pixel 


save_under 


event_mask 


do_not_propagate_mask 
override_redirect 


colormap 


cursor 


Contents 


Provides a hint to the server about how the client wants it to manage 
obscured portions of the window. The hint does not guarantee the server 
will maintain window contents. The following are possible: 


¢ The constant WhenMapped—Advises the server that the client wants 
it to maintain the contents of obscured regions when the window is 
mapped. 

¢« The constant Always—Advises the server that the client wants it to 
maintain the contents of obscured regions even when the window is 
unmapped. The server might maintain complete contents of a window 
when part of the window is obscured. If the server maintains the 
contents, exposure events are not generated, but the server may stop 
maintaining contents at any time. 

* The constant NotUseful—Advises the server that it does not need to 
maintain the contents of the window. 


Indicates (with bits set to one) which bit planes of the window hold dynamic 
data that must be preserved if the window obscures or is obscured by 
another window. 


Defines what values to use in planes not specified by the backing_planes 
member. The server is free to save only specified bit planes and to 
regenerate the remaining planes with the specified pixel value. Bits that 
extend beyond the number per pixel of the window are ignored. 


Setting the save_under member to true informs the server that the client 
would like the contents of the screen saved when the window obscures 
them. Saving the contents of obscured portions of the screen is not 
guaranteed. 


Defines which types of events associated with the window the server 
should report to the client. See the complete table in Chapter 4. 


Defines which kinds of events should not be propagated to ancestors. 


Specifies whether calls to map and configure the window should override 
a request by another client to redirect those calls. Typically, this is used 

to inform a window manager not to tamper with the window, for example 
when the client is creating and mapping a menu. 


Specifies the color map, if any, that best reflects the colors of the window. 
The color map must have the same visual type as the window. If it does 
not, the server issues an error. 


Specifying a value for the cursor member causes the server to use a 
particular cursor when the pointer is in the window. 





Window Changes Data Structure 


The window changes data structure specifies and receives information 
about a window. You use the window changes data structure in the 
CONFIGURE WINDOW routine, when you want to reconfigure a window’s 
size, position, border, and stacking order. 
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The data structure for the VAX binding is shown in Figure 3-3, and 
information about members in the data structure is described in 
Table 3-5. 


Figure 3-3 Window Changes Data Structure (VAX Binding) 
















x$l_wehg_width 8 
2 
: 
x$l_wchg_sibling 20 
x$l_wchg_stack_mode 24 
Table 3-5 Members of the Window Changes Data Structure (VAX Binding) 
Member Name Contents 
X$L_WCHG_X Defines the x-coordinate of the new location of the window relative to the 


origin of its parent. The x and y coordinates specify the upper left outside 
corner of the window. 


X$L_WCHG_Y Defines the y-coordinate of the new location of the window relative to the 
origin of its parent. The x and y coordinates specify the upper left outside 
corner of the window. 


X$L_WCHG_WIDTH Defines the new width of the window, excluding the border. 
X$L_WCHG_HEIGHT Defines the new height of the window, excluding the border. 
X$L_WCHG_BORDER_WIDTH Specifies the new window border in pixels. 
X$L_WCHG_SIBLING Specifies the sibling window for stacking order. 
X$L_WCHG_STACK_MODE Defines how the window is restacked. 


The data structure for the MIT C binding is shown in Figure 3-4, 
and information about members in the data structure is described in 
Table 3-6. 
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Figure 3-4 Window Changes Data Structure (MIT C Binding) 





typedef struct { 
int x,y; 
int width, height; 
int border width; 
Window sibling; 
int stack_mode; 

} XWindowChanges 





Table 3-6 Members of the Window Changes Data Structure (MIT C 


Binding) 

Member 

Name Contents 

x Defines, with the y member, the new location of the window relative 
to the origin of its parent. 

y Defines, with the x member, the new location of the window relative 
to the origin of its parent. 

width Defines the new width of the window, excluding the border. 

height Defines the new height of the window, excluding the border. 

border_width Specifies the new window border in pixels. 

sibling Specifies the sibling window for stacking order. 

stack_mode Defines how the window is restacked. 








Window Attributes Data Structure 


The window attributes data structure specifies and receives information 
about a window. Use this data structure when you want to obtain the 
current attributes of a window with the GET WINDOW ATTRIBUTES 
routine. 


The data structure for the VAX binding is shown in Figure 3-5, and 
information about members in the data structure is described in 
Table 3-7. 


Figure 3-5 Window Attributes Data Structure (VAX Binding) 
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Figure 3-5 (Cont.) Window Attributes Data Structure (VAX Binding) 
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x$l_wdat_map_state 68 
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Table 3-7 Members of the Window Attributes Data Structure (VAX Binding) 
Member Name Contents 
X$L_WDAT_X Specifies the x-coordinate of the upper left outside corner of the 
window relative to its parent. 
X$L_WDAT_Y Specifies the y-coordinate of the upper left outside corner of the 
window relative to its parent. 
X$L_WDAT_WIDTH ea the width of the window, excluding the window border, in 


(continued on next page) 
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Table 3-7 (Cont.) Members of the Window Attributes Data Structure (VAX Binding) 


Member Name 


X$L_WDAT_HEIGHT 


X$L_WDAT_BORDER_WIDTH 
X$L_WDAT_DEPTH 
X$L_WDAT_VISUAL 


X$L_WDAT_ROOT 
X$L_WDAT_CLASS 


X$L_WDAT_BIT_GRAVITY 
X$L_WDAT_WIN_GRAVITY 


X$L_WDAT_BACKING_STORE 


X$L_WDAT_BACKING_PLANES 


X$L_WDAT_BACKING_PIXEL 


X$L_SWDA_SAVE_UNDER 


X$L_WDAT_COLORMAP 


X$L_WDAT_MAP_ INSTALLED 


Contents 


Specifies the height of the window, excluding the window border, in 
pixels. 


Specifies the width of the window border in pixels. 
Specifies the bits per pixel of the window. 


The VISUAL structure associated with the window. The VISUAL 
structure specifies how displays should treat color resources. 


Identifies the screen with which the window is associated. 


Specifies whether the window accepts input and output, or input 
only. 


Specifies how pixels should be moved when the window is resized. 


Specifies how the window should be repositioned when its parent is 
resized. 


Indicates whether or not the server should maintain a record 
of portions of a window that are obscured when the window is 
mapped. In this release clients must maintain window contents. 


indicates (with bits set to 1) which bit planes of the window hold 
dynamic data that must be preserved in backing stores and during 
save unders. In this release clients must maintain their own data. 


Defines what values to use in planes not specified by 
X$L_WDAT_BACKING_PLANES. In this release clients must 
maintain their own values. 


Setting this member to true informs the server that the client would 
like the contents of the screen saved when the window obscures 
them. Saving the contents of obscured portions of the screen is not 
guaranteed. 


Specifies the color map, if any, that best reflects the colors of the 
window. The color map must have the same visual type as the 
window. If it does not, an error occurs. 


If set to true, indicates that the color map is currently installed and 
the window is being displayed in its correct colors. 


(continued on next page) 
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Table 3-7 (Cont.) Members of the Window Attributes Data Structure (VAX Binding) 


Member Name 


X$L_WDAT_MAP_STATE 


X$L_WDAT_ALL_EVENTS_MASK 


X$L_WDAT_YOUR_EVENT_MASK 
X$L_WDAT_DO-NOT_PROPAGATE_MASK 


X$L_WDAT_OVERRIDE_REDIRECT 


X$L_WDAT_SCREEN 


Contents 


Indicates whether the window is mapped and viewable. Clients can 
specify the following constants: 


Constant Name Description 
x$c_is_unmapped Indicates that the window is not mapped. 
x$c_is_unviewable Indicates that the window is mapped, but 


that one of its ancestors is unmapped, 
causing the window to be unviewable. 


x$c_is_viewable Indicates that the window is mapped and 
viewable. 


Indicates the set of events in which all applications have an interest. 
X$L_WDAT_ALL_EVENTS_MASK is the inclusive-OR of all event 
masks set for the window. 


Indicates the events about which the querying client is interested in 
receiving notice. 


Defines which events should not be propagated to its ancestors 
when no application has the event type selected in the window. 


Specifies whether requests to map and configure the window 
should override a request by another client to redirect those calls. 
Typically, this mask, which informs the window manager not to 
tamper with the window, should be used only on subwindows such 
as menus. 


Specifies the screen on which the window is mapped. 


The data structure for the MIT C binding is shown in Figure 3-6, and 
information about members in the data structure is described in Table 3-8. 
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Figure 3-6 Window Attributes Data Structure (MIT C Binding) 


typedef struct { 


int x,y; 

int width, height; 

int border_width; 

int depth; 

Visual *visual 

Window root; 

int class; 

int bit _gravity; 

int win_gravity; 

int backing store; 

unsigned long backing planes; 
unsigned long backing pixel; 
Bool save_under; 

Colormap colormap; 

Bool map_installed; 

int map_state; 

long all_event_masks; 

long your_event_mask; 

long do_not_propagate_mask; 
Bool override redirect; 
Screen *screen 


} XWindowAttributes 


Table 3-8 Members of the Window Attributes Data Structure (MIT C Binding) 


Member Name 


Contents 





x 


y 


width 

height 
border_width 
depth 

visual 


root 

class 
bit_gravity 
win_gravity 


backing_store 


Specifies, with the y member, the coordinates of the upper left corner of 
the window relative to its parent. 


Specifies, with the x member, the coordinates of the upper left corner of 
the window relative to its parent. 


Specifies the width of the window, excluding the window border, in pixels. 
Specifies the height of the window, excluding the window border, in pixels. 
Specifies the width of the window border in pixels. 

Specifies the bits per pixel of the window. 


A pointer to a VISUAL structure associated with the window. The VISUAL 
structure specifies how displays should treat color resources. 


Identifies the screen with which the window is associated. 
Specifies whether the window accepts input and output, or input only. 
Specifies how pixels should be moved when the window is resized. 


Specifies how the window should be repositioned when its parent is 
resized. 


Indicates whether or not the server should maintain a record of portions of 
a window that are obscured when the window is mapped. In this release 
clients must maintain contents of obscured windows. 


(continued on next page) 
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Table 3-8 (Cont.) Members of the Window Attributes Data Structure (MIT C Binding) 


Member Name 


backing_planes 


backing_pixel 


save_under 


colormap 


map_installed 


map_state 


all_events_mask 


your_event_mask 
do_not_propagate 


override_redirect 


screen 


Contents 


Indicates (with bits set to 1) which bit planes of the window hold dynamic 
data that must be preserved in backing stores and during save unders. 
In this release clients must maintain data to be preserved. 


Defines what values to use in planes not specified by the backing_planes 
member. In this release clients must maintain values to be saved. 


Setting the save_under member to true informs the server that the client 
would like the contents of the screen saved when the window obscures 
them. Saving the contents of obscured portions of the screen is not 
guaranteed. 


Specifies the color map, if any, that best reflects the colors of the window. 
The color map must have the same visual type as the window. If it does 
not, an error occurs. 


If set to true, the map_installed member indicates that the color map is 
currently installed and the window is being displayed in its correct colors. 


Indicates whether the window is mapped. Clients can specify the following 
constants: 


Constant 
Name Description 
IsUnmapped Indicates that the window is not mapped 


IsUnviewable Indicates that the window is mapped, but that one of 
its ancestors is unmapped, causing the window to be 
unviewable 


IsViewable Indicates that the window is mapped and viewable 


Indicates the set of events in which all applications have an interest. The 
all_events_mask member is the inclusive-OR of event masks set for the 
window. 


Indicates the events about which the querying application is interested in 
receiving notice. : 


Defines which events should not be propagated to its ancestors when no 
application has the event type selected in the window. 


Specifies whether requests to map and configure the window should 
override a request by another client to redirect those calls. Typically, this 
mask, which informs the window manager not to tamper with the window, 
should be used only on subwindows such as menus. 


Specifies the screen on which the window is mapped. 
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CHANGE WINDOW ATTRIBUTES 


Sets the attributes of a specified window. 





VAX FORMAT X$CHANGE_WINDOW_ATTRIBUTES 
(display, window __id, attributes_mask, attributes) 


argument 
information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
attributes_mask — uns longword uns longword read reference 
attributes record x$set_win_ read reference 
attributes 





MIT C FORMAT XChangeWindowaAtiributes 
(display, window _id, attributes_mask, attributes) 


argument 
information XChangeWindowAttributes (display, window_id, attributes_mask, 
attributes) 
Display *display; 
Window window_id; 
unsigned long attributes_mask; 
XSetWindowAttributes *attributes; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window whose attributes are to be changed. The 
identifier of the window was originally specified by any CREATE 
WINDOW request. 


aitributes_mask 

The window attributes defined in the attributes argument that will be 
changed. If the value of attributes_mask is 0, the attributes argument 
is ignored and is not referenced. See Table 3-9. 
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Table 3-9 CHANGE WINDOW ATTRIBUTES Flags 


Flag Name 


x$m_cw_back_pixmap 


x$m_cw_background_pixel 
x$m_cw_border_pixmap 


x$m_cw_border_pixel 
x$m_cw_bit_gravity 
x$m_cw_win_gravity 


x$m_cw_backing_store 
x$m_cw_backing_planes 


x$m_cw_backing_pixel 


x$m_cw_override_redirect 


x$m_cw_save_under 
x$m_cw_event_mask 


x$m_cw_dont_propagate 


x$m_cw_colormap 
x$m_cw_cursor 


attributes 


Member 


X$L_SWDA_BACKGROUND_PIXMAP 
X$L_SWDA_BACKGROUND PIXEL 
X$L_SWDA_BORDER_PIXMAP 
X$L_SWDA_BORDER_PIXEL 
X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 
X$L_SWDA_BACKING_STORE 
X$L_SWDA_BACKING_PLANES 
X$L_SWDA_BACKING_PIXEL 
X$L_SWDA_OVERRIDE_REDIRECT 
X$L_SWDA_SAVE_UNDER 
X$L_SWDA_EVENT_MASK 
X$L_SWDA_DO_NOT_PROPAGATE_MASK 
X$L_SWDA_COLORMAP 
X$L_SWDA_CURSOR 


A pointer to the attribute data structure containing values to be changed. 


For more information about the set window attributes data structure, see 


Section 3.1. 





DESCRIPTION CHANGE WINDOW ATTRIBUTES sets specific window attributes for a 


specified window. 


Depending on which attributes are specified in attributes, CHANGE 
WINDOW ATTRIBUTES can affect the specified window as follows: 


¢ Changing the background does not change the window contents. 


¢ Changing the background of a root window to None or ParentRelative 
restores the default background pixmap. 


* Changing the window gravity does not affect the current window 


position. 


¢ Changing the color map of a window generates a Colormap Notify 


event. 


¢ Changing the cursor of a root window to None restores the default 


cursor. 


¢ Ifa client attempts to select the Substructure Redirect event, the 
Resize Redirect event, or the Button Press event and another client 
has already selected it, the X server generates a Bad Access error. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_ACCESS BadAccess Possible causes are as follows: 


+ An attempt to grab a key/button 
combination that has already been 
grabbed by another client 

* An attempt to free a color map entry 
that was not allocated by the client 

* An attempt to store in to a read-only 
or unallocated color map entry 

« An attempt to modify the access 
conrol list from other than the local 
host 

« An attempt to select an event type 
that at most one client can select at a 
time, when another client has already 
selected it 


X$C_BAD_COLOR BadColor A value that you specified for a color map 
argument does not name a defined color 
map. 

X$C_BAD_ CURSOR _ BadCursor A value that you specified for a cursor 
argument does not name a defined 
cursor. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

*« One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 


attribute. 

X$C_BAD_PIXMAP BadPixmap A value that you specified for a pixmap 
argument does not name a defined 
pixmap. 

X$C_BAD_VALUE BadValue Some numeric values fall outside the 


range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


X$C_BAD_WINDOW — BadWindow A value that you specified for a window 
argument does not name a defined 
window. 
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CIRCULATE SUBWINDOWS 


Circulates the appropriate child of a window in a specified direction. 





VAX FORMAT X$CIRCULATE_SUBWINDOWS 
(display, window_id, direction) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
direction longword longword read reference 





MITC FORMAT XCirculateSubwindows 
(display, window_id, direction) 


argument 

information XCirculateSubwindows (display, window_id, direction) 
Display *display; 
Window window_id; 
int direction; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the parent of the window that you want to circulate. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 


direction 
The direction in which you want to circulate the window. Valid values are 
listed as follows: 


VAX Cc Description 


X$C_RAISE_LOWEST RaiseLowest The lowest window in the same stack 
as the specified window is raised. 


X$C_LOWER_HIGHEST __LowerHighest The highest window in the same stack 
as the specified window is lowered. 
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DESCRIPTION CIRCULATE SUBWINDOWS circulates children of a window in a specified 
direction. 


If the specified direction is Raise Lowest, CIRCULATE SUBWINDOWS 
raises the lowest mapped child Gf any) that is occluded by another child 
to the top of the stack. If the specified direction is Lower Highest, 
CIRCULATE SUBWINDOWS lowers the highest mapped child Gif any) 
that occludes another child to the bottom of the stack. 


If another client selects the Substructure Redirect event on the window 
specified in window_id, CIRCULATE SUBWINDOWS generates a 
circulate request event and performs no further processing. 





X ERRORS 


VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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CIRCULATE SUBWINDOWS DOWN 


Lowers the highest mapped child window of a window that occludes another 
window. 





VAX FORMAT X$CIRCULATE_SUBWINDOWS_ DOWN 
(display, window_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XCirculateSubwindowsDown 
(display, window_id) 


argument 

information XCirculateSubwindowsDown (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the parent window of the highest mapped child window. 


The identifier of the parent window was originally returned by any 
CREATE WINDOW request. 





DESCRIPTION CIRCULATE SUBWINDOWS DOWN lowers the highest mapped child of 
a window that partially or completely occludes another child window. 


Lowering the child window generates exposure events on any window that 
the child window had occluded. 


If another client has selected Substructure Redirect on the window 
specified in window_id, CIRCULATE SUBWINDOWS DOWN generates 
a circulate request event and performs no further processing. 
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X ERRORS 
VAX Cc Description 


X$C_BAD_WINDOW — BadWindow A value that you specified for a window 
argument does not name a defined window. 
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CIRCULATE SUBWINDOWS UP 


Raises the lowest mapped child of an occluded window. 





VAX FORMAT X$CIRCULATE_SUBWINDOWS_UP 
(display, window_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XCirculateSubwindowsUp 
(display, window_id) 


argument 

information XCirculateSubwindowsUp (display, window_id) 
Display *display; 
Window window _id; 


ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





window _id 

The identifier of the parent of the lowest mapped child window. The 
identifier of the window was originally returned by any CREATE 
WINDOW request. 





DESCRIPTION CIRCULATE SUBWINDOWS UP raises the lowest mapped child of a 
partially or completely occluded window. 


Raising the child window generates exposure events on portions of the 
child window that had been occluded, as well as on any descendants of the 
child window. CIRCULATE SUBWINDOWS UP also generates a Circulate 
Notify event. 


If another client has selected Substructure Redirect on the window 
specified in window_id, CIRCULATE SUBWINDOWS UP generates a 
circulate request event and performs no further processing. 
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X ERRORS 
VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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CONFIGURE WINDOW 


Reconfigures a window’s size, position, border, and stacking order. 





VAX FORMAT 


argument 
information 


X$CONFIGURE_WINDOW 
(display, window_id, change_mask, values) 


Argument Usage Data Type Access Mechanism 


display identifier uns longword read reference 
window_id identifier uns longword read reference 
change_mask mask_uns uns longword read reference 
longword 
values record x$window_ read reference 
changes 





MITC FORMAT XConfigureWindow 


(display, window_id, change_mask, values) 





argument 
information XConfigureWindow(display, window_id, change_mask, values) 
Display *display; 
Window window_id; 
unsigned int change_mask; 
XWindowChanges *values; 
ARGUMENTS _ display 
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The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window to be reconfigured. The identifier of the 
window was originally returned by any CREATE WINDOW request. 


change_mask 
A bit mask that specifies the values that are to be set using the 
information in the data structure that the values argument points to. 


Table 3-10 lists each bit for the change_mask argument, its predefined 
value, and its description. 


Window Routines 
CONFIGURE WINDOW 


Table 3-10 Change Mask Bits 


Bit VAX Value C Value Meaning when Set 
0 X$C_CW_X CWY Change x-coordinate 
1 X$C_CW_Y CWY Change y-coordinate 
2 X$C_CW_WIDTH CWWidth Change width 

3 X$C_CW_HEIGHT CWHeight Change height 

4 X$C_CW_BORDER_WIDTH CWBWidth Change border width 
5 X$C_CW_SIBLING CWSibling Change sibling 

6 X$C_CW_STACK_MODE CWStackMode Change stack mode 
7 NONE None Reserved 

8 NONE None Reserved 
values 


A pointer to the window changes data structure. 


For more information about the window changes data structure, see 
Section 3.2. 





DESCRIPTION 


CONFIGURE WINDOW reconfigures a window’s size, position, border, and 
stacking order. 


A Bad Match error is generated if a sibling is specified without a stack 
mode or if the window is not actually a sibling. Note that the computations 
for stack mode are performed with respect to the window’s final geometry, 
not its initial geometry. Any backing store contents of the window, its 
inferiors, and other newly visible windows are either discarded or changed 
to reflect the current screen contents. 





X ERRORS 


VAX Cc Description 
X$C_BAD_MATCH BadMatch Possible causes are as follows: 


+ In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

* — An input-only window lacks this 
attribute. 
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Window Routines 
CONFIGURE WINDOW 


VAX Cc 


X$C_BAD_VALUE BadValue 


X$C_BAD_WINDOW — BadWindow 
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Description 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


A value that you specified for a window 
argument does not name a defined window. 


CREATE SIMPLE WINDOW 


Creates a subwindow of a specified parent window. 


Window Routines 


CREATE SIMPLE WINDOW 





VAX FORMAT 


argument 
information 


window_id_return = X$CREATE_SIMPLE_WINDOW 
(display, parent_id, x_coord, y_coord, width, height, 
border_width, border_id, background_id) 


Argument 


window_id_return 


display 
parent_id 
x_coord 
y_coord 

width 

height 
border_width 
border_id 
background_id 


Usage 
identifier 
identifier 
identifier 
longword 
longword 

uns longword 
uns longword 
uns longword 
identifier 
identifier 


Data Type 


uns longword 
uns longword 
uns longword 
longword 

longword 

uns longword 
uns longword 
uns longword 
uns longword 
uns longword 


Access 


write 
read 
read 
read 
read 
read 
read 
read 
read 
read 


Mechanism 


value 

reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 





MIT C FORMAT window_id_return = XCreateSimpleWindow 
(display, parent_id, x_coord, y_coord, width, height, 
border_width, border_id, background_id) 


argument 
information 


Window XCreateSimpleWindow(display, parent_id, x_coord, y_coord, 


width, height, border_width, 


border_id, background_id) 


Display *display; 
Window parent_id; 
int x_coord, y coord; 
unsigned int width, height, border width; 


unsigned long border_id; 


unsigned long background_id; 





RETURNS 


window _id_return 


The identifier of the new subwindow. 
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Window Routines 
CREATE SIMPLE WINDOW 








ARGUMENTS _~ display 
The display information originally returned by OPEN DISPLAY. 
parent_id 
The identifier of the parent window. 
x_coord 
The x-coordinate of the new subwindow. This coordinate is relative to the 
inside of the parent window. The x- and y-coordinates define the upper left 
corner of the new subwindow. 
y_coord 
The y-coordinate of the new subwindow. This coordinate is relative to the 
inside of the parent window. The x- and y-coordinates define the upper left 
corner of the new subwindow. 
width 
The width of the new subwindow. The width and height represent the 
outline of the new subwindow. 
Width and height represent the new subwindow’s inside dimensions; 
they do not include the new subwindow’s borders, which are outside the 
window. 
height 
The height of the new subwindow. The height and width represent the 
outline of the new subwindow. 
Height and width represent the new subwindow’s inside dimensions; 
they do not include the new subwindow’s borders, which are outside the 
window. 
border_width 
The width, in pixels, of the new subwindow’s border. 
border _id 
The identifier of the pixmap used to specify the border pattern. 
background_id 
The identifier of the pixmap that specifies the background. 

DESCRIPTION CREATE SIMPLE WINDOW creates a subwindow of a specified parent 
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window from an application. The identifiers of the pixmaps were originally 
returned by CREATE PIXMAP. 


CREATE SIMPLE WINDOW returns the window identifier of the new 
subwindow. All subsequent operations that are performed on the new 
subwindow use this window identifier as the identifier of that window. 
The window identifier remains associated with the subwindow until you 
destroy it. 


Window Routines 
CREATE SIMPLE WINDOW 


The outline of the new subwindow is defined by the arguments x_coord, 
y_coord, width, and height. The x- and y-coordinates are relative to the 
inside of the parent window and define the upper left corner of the new 
subwindow. The width and height determine the area inside the window 
of the border. The width and height must be nonzero; otherwise a Bad 
Value error is returned. 


If the border width is specified, the x- and y-coordinates specify the origin 
at the border, and the origin of the window is offset by the border width. 


When you create a window with the CREATE SIMPLE WINDOW routine, 
the new window inherits the depth, class, and visual identifier of the 
parent window. You cannot change these attributes. Upon creation, the 
new subwindow does not have an associated icon window in the property 
list. The name of the new subwindow is the null string. 


Once you create a window with the CREATE SIMPLE WINDOW routine, 
you must then call the MAP WINDOW routine to display the window 

on the screen. In order for the window to appear on the screen, all of 
the window’s ancestors must also be mapped, and the window cannot be 
obscured by any of its ancestors. The new subwindow does not have its 
own cursor at creation time; its uses the parent window’s cursor until its 
own cursor is registered. 


The CREATE SIMPLE WINDOW routine generates a Create Notify event. 


To create a subwindow and specify its attributes, use the CREATE 
WINDOW routine. 





X ERRORS 


VAX Cc Description 

X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 
resource for any cause. 

X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

« — An input-only window lacks this 
attribute. 
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Window Routines 
CREATE SIMPLE WINDOW 


VAX Cc 


X$C_BAD_VALUE BadValue 


X$C_BAD_WINDOW — BadWindow 
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Description 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


A value that you specified for a window 
argument does not name a defined window. 


CREATE WINDOW 


Window Routines 
CREATE WINDOW 


Creates a subwindow of a parent window and defines the attributes of the 


subwindow. 





VAX FORMAT 


argument 


information 


window_id_return = X$CREATE_WINDOW 
(display, parent_id, x_coord, y_coord, width, 


height, border_width, depth, class, visual_struc, 
attributes_mask, attributes) 


Argument 
window_id_ 
return 
display 
parent_id 
x_coord 
y_coord 
width 

height 
border_width 
depth 

class 
visual_struc 


attributes_mask 


attributes 


Usage 


identifier 


identifier 
identifier 
longword 
longword 

uns longword 
uns longword 
uns longword 
longword 
longword 
record 

uns longword 
record 


Data Type 


uns longword 


uns longword 
uns longword 
longword 
longword 

uns longword 
uns longword 
uns longword 
longword 
longword 
x$visual 

uns longword 


x$set_win_ 
attributes 


Access 


write 


read 
read 
read 
read 
read 
read 
read 
read 
read 
read 
read 
read 


Mechanism 


reference 


reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 





MIT C FORMAT window_id_return = XCreateWindow 


(display, parent_id, x_coord, y_coord, width, 


height, border_width, depth, class, visual_struc, 
attributes_mask, attributes) 
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Window Routines 


CREATE WINDOW 


argument 
information 


Window XCreateWindow (display, parent_id, x_coord, y_ coord, width, 
height, border width, depth, class, 
visual_struc, attributes mask, attributes) 

Display *display; 

Window parent_id; 

int x coord, y_ coord; 

unsigned int width, height; 
unsigned int border width; 

int depth; 

unsigned int class; 

Visual *visual_struc; 

unsigned long attributes mask; 
XSetWindowAttributes *attributes; 





RETURNS 


window _id_return 
The identifier of the new subwindow that is created. 





ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


parent_id 


The identifier of the window that is the parent of the new subwindow. 


x_coord 

The x-coordinate of the new subwindow. This coordinate is relative to the 
inside of the parent window. The x- and y-coordinates define the upper left 
corner of the new subwindow. 


y_coord 

The y-coordinate of the new subwindow. This coordinate is relative to the 
inside of the parent window. The x- and y-coordinates define the upper left 
corner of the new subwindow. 


width 
The width, in pixels, of the new subwindow. The width and height 
determine the area of the new subwindow. 


The width and the height arguments represent the new subwindow’s 
inside dimensions; they do not include the new subwindow’s borders, 
which are outside the window. 


height 


The height, in pixels, of the new subwindow. The height and width 
determine the area of the new subwindow. 


The height and the width arguments represent the new subwindow’s 
inside dimensions; they do not include the new subwindow’s borders, 
which are outside the window. 


border_width 

The width, in pixels, of the new subwindow’s border. For input-only 
windows, border_width must be zero, otherwise a Bad Match error is 
generated. 


Window Routines 
CREATE WINDOW 


depth 

The depth, in bits per pixel, of the new subwindow. If the value of depth 
equals zero and the class argument is either input output or Copy From 
Parent, the depth of the new subwindow is the same as the depth of the 

parent window. For input only windows, depth must be zero. 


class 


The class of the new subwindow. 


If the parent window is input only, the class of the subwindow cannot be 
input output. 


A window with a class of input only cannot be used as output. 


For Copy From Parent windows, the class of the new subwindow is the 
same as the parent window. 


visual_struc 


A pointer to a visual structure associated with the window. 


attributes_mask 

The window attributes to be specified in the attributes argument. For 
any attributes not specified, default values are used. If the value of 
attributes_mask is zero, the attributes argument is ignored and is not 
referenced. 


attributes 


A pointer to the set window attributes data structure for the window. 





DESCRIPTION 


CREATE WINDOW creates a subwindow of a specified parent window and 
sets the attributes of the new subwindow. CREATE WINDOW returns the 
window identifier of the new subwindow. All subsequent operations that 
are performed on the new subwindow use this window identifier as the 
identifier of that window. The window identifier remains associated with 
the new subwindow until you destroy the new subwindow. 


The outline of the new subwindow is defined by the arguments x_coord, 
y_coord, width, and height. The x- and y-coordinates are relative to the 
inside of the parent window and define the upper left corner of the new 
subwindow. The width and height determine the area inside the border. 
The width and height must be nonzero, otherwise a Bad Value error is 
returned. 


If the border width is specified, the x- and y-coordinates specify the origin 
at the border, and the origin of the window is offset by the border width. 


An input-only window cannot process graphics requests, exposure events, 
or visibly notify events. In addition, an input-only window cannot be used 
as a drawable (a source or destination for graphics requests). Input-only 
and input-output windows act identically in all other respects. Only the 
following window attributes are defined for input-only windows: 


e Window gravity 
e Event mask 


¢ Do not propagate mask 
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Window Routines 


CREATE WINDOW 


e Override redirect 


e Cursor 


If you specify any other attribute for an input only window, a Bad Match 
error is generated. 


The CREATE WINDOW routine generates a Create Notify event. 


CREATE WINDOW differs from CREATE SIMPLE WINDOW because 

it lets you specify the new subwindow’s attributes, such as class, visual 
type, and attributes contained in the set window attributes data structure. 
With CREATE SIMPLE WINDOW, these attributes are automatically 
inherited from the parent window. You specify the attributes of the new 
subwindow by setting the appropriate bits in attributes_mask to indicate 
the attributes that are set in attributes. For more information about the 
set window attributes data structure, see Section 3.1. 





X ERRORS 
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VAX Cc Description 

X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 
resource for any cause. 

X$C_BAD_COLOR BadColor A value that you specified for a color map 
argument does not name a defined color 
map. 

X$C_BAD_ BadCursor A value that you specified for a cursor 

CURSOR argument does not name a defined cursor. 

X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

« An input-only window is used as a 
drawable. 

« One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

¢ — An input-only window lacks this attribute. 


X$C_BAD_PIXMAP —_ BadPixmap A value that you specified for a pixmap 
argument does not name a defined pixmap. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the range 
of values accepted by the request. Uniess a 
specific range is specified for an argument, 
the full range defined by the argument’s type 
is accepted. Any argument defined as a set 
of alternatives can generate this error. 


X$C_BAD_ BadWindow A value that you specified for a window 
WINDOW argument does not name a defined window. 





Window Routines 
DESTROY SUBWINDOWS 


DESTROY SUBWINDOWS 


Destroys all subwindows of a window. 





VAX FORMAT X$DESTROY_SUBWINDOWS 
(display, window _id) 


argument 


information Argument ‘Usage = DataType ——Access_~—“ Mechanism _ 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XDestroySubwindows 
(display, window_id) 


argument 

information XDestroySubwindows (display, window_id) 
Display *display; 
Window window _id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window for which all subwindows are to be destroyed. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 





DESCRIPTION DESTROY SUBWINDOWS destroys all subwindows (children) of a 
specified window in bottom-to-top stacking order. 


After you destroy a subwindow, you cannot reference that subwindow 
again. If any mapped subwindows are destroyed, DESTROY 
SUBWINDOWS generates exposure events on the window specified in 
window_id. 


When you want to destroy not only the subwindows of a given window, but 
also the window itself, use DESTROY WINDOW. 
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Window Routines 
DESTROY SUBWINDOWS 





X ERRORS 
VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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Window Routines 
DESTROY WINDOW 


DESTROY WINDOW 


Destroys a window and all of its subwindows. 





VAX FORMAT 


argument 
information 


X$DESTROY_WINDOW (display, window_id) 


Argument Usage Data Type Access Mechanism 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XDestroyWindow (display, window_id) 


argument 
information 


XDestroyWindow (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window to be destroyed. The identifier of the window 
was originally returned by any CREATE WINDOW request. 





DESCRIPTION 


DESTROY WINDOW unmaps and destroys the specified window and all of 
its subwindows. 


If the specified window was mapped before calling DESTROY WINDOW, 
the window is unmapped automatically. The window and all subwindows 
are then destroyed, and a destroy notify event is generated for each 
window. Destroy notify events are first generated for the inferiors or 
ancestors of the window before being generated on the window itself. 


If you specify a root window, no windows are destroyed. 


Once you destroy a window, you cannot reference that window again. 
Destroying a mapped window generates exposure events on other windows 
that the destroyed window had obscured. 


When you want to destroy only the subwindows of a given window, use 
DESTROY SUBWINDOWS. 


Window Routines 
DESTROY WINDOW 





X ERRORS 
VAX Cc Description 


X$C_BAD_ WINDOW — BadWindow A value that you specified for a window 
argument does not name a defined window. 
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GET GEOMETRY 


Obtains the current geometry of the specified drawable. 





VAX FORMAT _ siatus_return = X$GET_GEOMETRY 
(display, drawable_id [,window_id_return] 
[,x_coord_return] [,y_coord_return] [,width_return] 
[,height_return] [,border_width_return] [,depth_return]) 
argument 
information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
window_id_return identifier uns longword write reference 
x_coord_return longword longword write reference 
y_coord_return longword longword write reference 
width_return uns longword uns longword write reference 
height_return uns longword uns longword write reference 
border_width_ uns longword uns longword write reference 
return 
depth_return longword longword write reference 





MIT C FORMAT _siatus_return = XGetGeometry 
(display, drawable_id, window_id_return, 
x_coord_return, y_coord_return, width_return, 
height_return, border_width_return, depth_return) 

argument 

information Status XGetGeometry (display, drawable id, window_id_ return, 


x coord return, y_coord_return, width_return, 
height_return, border _width_return, 
depth_return) 

Display *display; 

Drawable drawable _id; 

Window *window_id_return; 

int *x_coord_return, *y coord return; 

unsigned int *width_return, *height_return; 

unsigned int *border_width_return; 

unsigned int *depth_return; 
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Window Routines 
GET GEOMETRY 





RETURNS status_return 


Specifies whether or not the routine completed successfully. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the drawable for which the current geometry is to be 
obtained. This can be either a window or a pixmap. 


window_id_return 
The identifier of the root window of the specified drawable. 


VAX only 
This argument is optional. 


x_coord_return 


If the drawable is a window, x_coord_return specifies the x-coordinate of 
the window. The x- and y-coordinates define the upper left corner of the 
window, relative to the origin of the parent window. If the drawable is a 
pixmap, x_coord_return and y_coord_return equal zero. 

VAX only 

This argument is optional. 

y_coord_return 

If the drawable is a window, y_coord_return specifies the y-coordinate of 
the window. The x- and y-coordinates define the upper left corner of the 
window, relative to the origin of the parent window. If the drawable is a 
pixmap, x_coord_return and y_coord_return equal zero. 

VAX only 

This argument is optional. 

width_return 

The width, in pixels, of the drawable. GET GEOMETRY returns the width 


of the drawable to this argument. The width and height represent the 
inside area of the drawable, not including the border of the drawable. 


VAX only 


This argument is optional. 
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height_return 

The height, in pixels, of the drawable. GET GEOMETRY returns the 
height of the drawable to this argument. The width and height represent 
the inside area of the drawable, not including the border of the drawable. 


VAX only 
This argument is optional. 


border_width_return 

The width, in pixels, of the new subwindow’s border. If the drawable is 
a window, GET GEOMETRY returns the width of the window’s border to 
this argument. If the drawable is a pixmap, GET GEOMETRY returns 
zero to this argument. 


VAX only 


This argument is optional. 


depth_return 

The depth of the pixmap. The depth must be supported by the root window 
of the specified drawable. GET GEOMETRY returns the depth, in bits per 
pixel, to this argument. 


VAX only 
This argument is optional. 





DESCRIPTION 


GET GEOMETRY obtains the current geometry of the specified drawable. 


If the specified drawable is a pixmap, GET GEOMETRY returns the width, 
height, and depth of the pixmap. GET GEOMETRY returns zero for the 
x_coord_return, y_coord_return, and border_width_return 
arguments when the specified drawable is a pixmap. 


If the specified drawable is a window, GET GEOMETRY returns the 

x- and y-coordinates of the upper left corner of the window (relative to 
its parent’s origin), along with the width and height of the window and 
the width of the window's border. GET GEOMETRY returns zero for the 
depth_return argument when the drawable is a window. 





X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE _ BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


Window Routines 
GET WINDOW ATTRIBUTES 


GET WINDOW ATTRIBUTES 


Obtains the attributes of a specified window. 





VAX FORMAT _ status_return = X$GET_WINDOW_ATTRIBUTES 
(display, window_id, window_attributes_return) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
window_attributes_ array x$window__ write reference 
return attributes 





MIT C FORMAT -sstatus_return = XGetWindowaAttributes 
(display, window_id, window_attributes_return) 





argument 
information Status XGetWindowAttributes (display, window_id, 
window attributes return) 
Display *display; 
Window window _id; 
XWindowAttributes *window_attributes_ return; 
RETURNS status_return 


Return value that specifies whether the routine completed successfully. 


C only 


This argument returns 1 if the routine completes successfully, and zero if 
it does not complete successfully. 


VAX only 


This argument returns one of the following values: 
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Value Description 


X$_ERRORREPLY Error received from the server—window no longer exists. 
SS$_ NORMAL Success. 
Otherwise Failure for reason given. 





ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window whose attributes are to be obtained. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 


window_attributes_return 

A pointer to an array of attribute data structures, in which each element 
defines a window attribute. For more information about the window 
attributes data structure, see Section 3.3. 





DESCRIPTION 


GET WINDOW ATTRIBUTES obtains the current attributes for a window. 


GET WINDOW ATTRIBUTES returns a status value that specifies 
whether or not the routine completed successfully. This value is zero if 
the routine fails and nonzero if the routine succeeds. 





X ERRORS 


VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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LOWER WINDOW 


Lowers a window so that it does not obscure any sibling windows. 





VAX FORMAT X$LOWER_WINDOW (display, window_id) 


argument 


information Argument ‘Usage = —~—-‘DataType + =—-—sAccess.=—Ss Mechanism 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XLowerWindow (display, window_id) 


argument 

information XLowerWindow (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window that you want to lower. The identifier of the 
window was originally returned by any CREATE WINDOW request. 





DESCRIPTION LOWER WINDOW lowers a window so that it does not obscure any sibling 
windows. 


Lowering a window does not change the x- and y-coordinates of the 
window. Lowering a mapped window generates exposure events for any 
windows that had been obscured. 


If the override attribute of the window is false and another client has 
selected the Substructure Redirect event on the parent window, LOWER 
WINDOW generates a configure request event and performs no further 
processing. 
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X ERRORS 
VAX Cc Description 


X$C_BAD_WINDOW — BadWindow A value that you specified for a window 
argument does not name a defined window. 
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MAP RAISED 


Maps the specified window and raises it to the top of the stack. 





VAX FORMAT X$MAP_RAISED (display, window _id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XMapRaised (display, window_id) 


argument 

information XMapRaised(display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window to be mapped and raised. The identifier of 
the window was originally returned by any CREATE WINDOW request. 





DESCRIPTION MAP RAISED maps and raises a specified window. 


MAP RAISED is basically the same routine as MAP WINDOW, except that 
it also raises the specified window to the top of the stack. 





X ERRORS 
VAX Cc Description 


X$C_BAD_WINDOW — BadWindow A value that you specified for a window 
argument does not name a defined window. 


Window Routines 
MAP SUBWINDOWS 


MAP SUBWINDOWS 


Maps all subwindows of a specified window. 





VAX FORMAT X$MAP_SUBWINDOWS (display, window _id) 


argument 


information Argument | Usage —‘DataType+=—Access_—Ss Mechanism 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XMapSubwindows (display, window_id) 


argument 

information XMapSubwindows (display, window_id) 
Display *display; 
Window  window_id; 





ARGUMENTS _~ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window for which all subwindows are to be mapped. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 





DESCRIPTION MAP SUBWINDOWS maps all subwindows for a specified window in 
top-to-bottom stacking order. 


MAP SUBWINDOWS generates an exposure event on each newly 
displayed window. 


When you want to map not only the subwindows of a window, but also the 
window itself, use MAP WINDOW. 





X ERRORS 
VAX Cc Description 
X$C_BAD_WINDOW _— BadWindow A value that you specified for a window 


argument does not name a defined window. 


3-47 


Window Routines 
MAP WINDOW 


MAP WINDOW 


Maps a window and all of its subwindows that have had mapping requests. 





VAX FORMAT X$MAP_WINDOW (display, window_id) 


argument 


information Argument | Usage —~—~—‘dData Type '+—=—~—=sAccess._~=—Ssés« Mechanism 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XMapWindow (display, window _id) 


argument 

information XMapWindow (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window to be mapped. The identifier of the window 
was originally returned by any CREATE WINDOW request. 


If the window specified in window_id has an unmapped ancestor, it is not 
displayed on the screen until the ancestor is also mapped. 


If the window specified in window_id is opaque, MAP WINDOW 
generates expose events on each opaque window that becomes displayed. 





DESCRIPTION MAP WINDOW maps a window and all of its subwindows that have had 
mapping requests. 


If you first map a window, then paint it, and then process input events, 
the window will be painted twice. To avoid painting a window twice, call 
SELECT INPUT for exposure events, then map the window, and then 
process input events. 


To map all subwindows of a given window, use MAP SUBWINDOWS. 
Using MAP WINDOW repeatedly is less efficient than using MAP 
SUBWINDOWS. To map a window and raise it to the top of a stack, 
use MAP RAISED. 


Window Routines 
MAP WINDOW 





X ERRORS 


VAX 
X$C_BAD_WINDOW 


Cc 
BadWindow 


Description 


A value that you specified for a window 
argument does not name a defined window. 


Window Routines 
MOVE RESIZE WINDOW 


MOVE RESIZE WINDOW 


Changes the location and the size of a specified window. 





VAX FORMAT 


argument 
information 


X$MOVE_RESIZE_WINDOW 
(display, window _id, x_coord, y_coord, width, height) 


Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width uns longword uns longword read reference 
height uns longword uns longword read reference 





MITC FORMAT XMoveResizeWindow 


(display, window_id, x_coord, y_coord, width, height) 





argument 
information XMoveResizeWindow (display, window_id, x_coord, y coord, width, 
height) 
Display *display; 
Window window_id; 
int x_coord, y_ coord; 
unsigned int width, height; 
ARGUMENTS _ display 
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The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window that will be changed in size and location. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 


X_coord 

The x-coordinate of the window’s new location. This coordinate is relative 
to the parent window. The x- and y-coordinates define the new location of 
the window’s upper left corner. 


Window Routines 
MOVE RESIZE WINDOW 


y_coord 

The y-coordinate of the window’s new location. This coordinate is relative 
to the parent window. The x- and y-coordinates define the new location of 
the window's upper left corner. 


width 
The new width, in pixels, of the window. The width and height define the 
interior area of the window. 


height 
The new height, in pixels, of the window. The width and height define the 
interior area of the window. 





DESCRIPTION MOVE RESIZE WINDOW changes the size and the location of a specified 
window. 


Configuring a mapped window causes the window to lose its contents 
and generates an exposure event. Configuring a window also generates 
exposure events on any other windows that the window had formerly 
obscured. 


If the override attribute of the window is false ana another client has 
selected substructure redirect on the parent window, MOVE RESIZE 
WINDOW generates a configure request event and performs no further 
processing. 


When you want to change only the size of a window, use RESIZE 
WINDOW. When you want to change only the location of a window, use 





MOVE WINDOW. 

X ERRORS 
VAX Cc Description 
X$C_BAD_MATCH BadMatch Possible causes are as follows: 


¢ In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* — An input-only window is used as a 
drawable. 

¢ One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

* — An input-only window lacks this 
attribute. 
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Window Routines 
MOVE RESIZE WINDOW 


VAX Cc 
X$C_BAD_VALUE BadValue 


X$C_BAD_WINDOW _ BadWindow 
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Description 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


A value that you specified for a window 
argument does not name a defined window. 


Window Routines 
MOVE WINDOW 


MOVE WINDOW 


Moves and raises a window without changing its size. 





VAX FORMAT X$MOVE_WINDOW 
(display, window _id, x_coord, y_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 





MITC FORMAT XMoveWindow 
(display, window_id, x_coord, y_coord) 


argument 

information XMoveWindow (display, window_id, x_coord, y_coord) 
Display *display; 
Window window_id; 
int x_coord, y_coord; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window to be moved. The identifier of the window 
was originally returned by any CREATE WINDOW request. 


X_coord 

The x-coordinate of the window’s new location. The x- and y-coordinates 
define the new location of the upper left corner of the window’s border (or 
the window itself if it has no border). 


y_coord 

The y-coordinate of the window’s new location. The x- and y-coordinates 
define the new location of the upper left corner of the window’s border (or 
the window itself if it has no border). 
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Window Routines 


MOVE WINDOW 





DESCRIPTION 


MOVE WINDOW moves and raises a window without changing its size. 


MOVE WINDOW does not change the mapping state of the window. 
Moving a mapped window generates exposure events on any windows 
that were obscured. However, if you move a mapped window, it may lose 
its contents if no backing store exists for the window and the window is 
obscured by windows other than its subwindows. If the window loses its 
contents, exposure events are generated for the window and any of its 
mapped subwindows. 


If the override attribute of the window is false and another client has 
selected substructure redirect on the parent window, MOVE WINDOW 
generates a configure request event and performs no further processing. 
The stacking order does not change. 


If you want to move a window and change its size, use CONFIGURE 
WINDOW or MOVE RESIZE WINDOW. 





X ERRORS 
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VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 


QUERY POINTER 


Window Routines 


QUERY POINTER 


Obtains the root window where the pointer is currently located and the pointer 
coordinates relative to the root window's origin. 





VAX FORMAT __ result_return = X$QUERY_POINTER 
(display, window_id, root_id_return [,child_id_return] 


[,root_x_coord_return] [,root_y_coord_return] 


[,win_x_coord_return] [,win_y_coord_return] 
[,state_mask_return]) 


argument 


information 
Argument 


result_return 

display 

window_id 
root_id_return 
child_id_return 
root_x_coord_return 
root_y_coord_return 
win_x_coord_return 
win_y_coord_return 
state_mask_return 


Usage 


longword 
identifier 
identifier 
identifier 
identifier 
longword 
longword 
longword 
longword 
uns longword 


Data Type 


longword 
uns longword 
uns longword 
uns longword 
uns longword 
longword 
longword 
longword 
longword 
uns longword 


Access 


write 
read 
read 
write 
write 
write 
write 
write 
write 
write 


Mechanism 


value 

reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 





MIT C FORMAT ss result_return = XQueryPointer 
(display, window_id, root_id_return, child_id_return, 
root_x_coord_return, root_y_coord_return, 
win_x_coord_return, win_y_coord_return, 
state_mask_return) 


argument 


information Bool XQueryPointer(display, window_id, root_id_return, 


child_id_ return, root_x_coord_return, 
root_y_coord return, win_x coord return, 


Display *display; 
Window window_id; 


Window *root_id_return, *child_id_ return; 


int *root_x_coord_return, *root_y coord_return; 
int *win_x coord_return, *win_y_coord_return; 
unsigned int *state_mask_return; 


win_y_coord_return, state_mask_return) 


Window Routines 
QUERY POINTER 





RETURNS result_return 
This argument specifies whether or not the pointer is on the same screen 
as the window specified in window_id. When true, this argument is a 
nonzero value. When false, this argument is zero. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 

The identifier of the window; this window is relative to the pointer to 
be queried. The identifier of the window was originally returned by any 
CREATE WINDOW request. 


root_id_return 

The identifier of the root window of the window specified in window_id. 
QUERY POINTER returns the root window where the pointer is currently 
located to this argument. 


child_id_return 

The identifier of the child window that contains the pointer coordinates. 
QUERY POINTER returns the child window where the pointer is located 
(if any) to this argument. 


VAX only 
This argument is optional. 


root_x_coord_return 

The x-coordinate of the pointer. This coordinate is relative to the root 
window’s origin. The x- and y-coordinates define the location of the 
pointer. QUERY POINTER returns the pointer coordinates (relative to 
the root window’s origin) to this argument. 


VAX only 


This argument is optional. 

root_y coord_return 

The y-coordinate of the pointer. This coordinate is relative to the root 
window’s origin. The x- and y-coordinates define the location of the 
pointer. QUERY POINTER returns the pointer coordinates (relative to 
the root window’s origin) to this argument. 

VAX only 


This argument is optional. 


Window Routines 
QUERY POINTER 


win_x_coord_return 

The x-coordinate of the window. This coordinate is relative to the root 
window’s origin. The x- and y-coordinates define the location of the 
pointer. QUERY POINTER returns the pointer coordinates (relative to 
the root window’s origin) to this argument. 


VAX only 
This argument is optional. 


win_y_coord_return 

The y-coordinate of the pointer. This coordinate is relative to the root 
window’s origin. The x- and y-coordinates define the location of the 
pointer. QUERY POINTER returns the pointer coordinates (relative to 
the root window’s origin) to this argument. 


VAX only 
This argument is optional. 


state_mask_return 
The current state of the modifier keys and the buttons. QUERY POINTER 
returns the current state to this argument. 


VAX only 
This argument is optional. 





DESCRIPTION 


QUERY POINTER obtains the root window where the pointer is currently 
located and the pointer coordinates relative to the root window’s origin. 


If QUERY POINTER returns zero, then win_x_coord_return and 
win_y_coord_return are equal to zero, because the pointer is not on 
the same screen as the root window and the child window. If QUERY 
POINTER returns a nonzero value, then win_x_coord_return and 
win_y_coord_return are the pointer coordinates relative to the origin of 
the window_id. 





X ERRORS 


VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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Window Routines 
QUERY TREE 


QUERY TREE 


Lists the parent, the children, and the number of children for a window. 





VAX FORMAT _ siatus_return = X$QUERY_TREE 


(display, window_id [,root_id_return] 
[,parent_id_return] [,children_return] 
[;num_children_return] [,children_size_return] 
[,children_buff_return]) 


argument 


information 
Argument 


status_return 
display 

window_id 
root_id_return 
parent_id_return 
children_return 
num_children_return 
children_size_return 
children_buff_return 


Usage 


longword 
identifier 
identifier 
identifier 
identifier 
address 

longword 
longword 
identifier 


Data Type 


longword 
uns longword 
uns longword 
uns longword 
uns longword 
uns longword 
longword 
longword 
uns longword 


Access 


write 
read 
read 
write 
write 
write 
write 
write 
write 


Mechanism 


value 

reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 





MIT C FORMAT -ssiatus_return = XQueryTree 


(display, window_id, root_id_return, parent_id_return, 


children_return, num_children_return]) 


argument 


information Status XQueryTree (display, window_id, root_id_return, 


Display *display; 
Window window_id; 


Window *root_id_ return; 
Window *parent_id_return; 
Window **children_return; 


unsigned int *num_children_return; 
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parent_id_return, children_return, 
num children return) 


Window Routines 
QUERY TREE 








RETURNS status_return 
Specifies whether the routine completed successfully. 
C only 
This argument returns 1 if the routine completes successfully, and zero if 
it does not complete successfully. 
VAX only 
This argument returns one of the following values: 
Value Description 
X$_ERRORREPLY Error received from the server—window no longer exists. 
SS$_NORMAL Success. 
Otherwise Failure for reason given. 
ARGUMENTS __ display 


The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window for which the window tree information is to 
be obtained. The identifier of the window was originally returned by any 
CREATE WINDOW request. 


root_id_return 
The identifier of the root window of the specified window. 


VAX only 


This argument is optional. 


parent_id_return 
The identifier of the parent window of the specified window. 


VAX only 


This argument is optional. 


children_return 

The virtual address of a pointer to an array of child windows, returned by 
the routine and residing in space reserved by Xlib. Each element in the 
array is a child window of the specified window. The number of elements 
in the array is specified by num_children_return. 


VAX only 
This argument is optional. 
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Window Routines 


QUERY TREE 


num_children_return 
The number of children associated with the specified window. 


VAX only 
This argument is optional. 
children_size_return (VAX only) 


The size of the buffer containing the child windows, specified in 
children_buff_return. 


children_buff_return (VAX only) 

A pointer to a data buffer, residing in space you have reserved, where each 
entry is one child window identifier. The size of the buffer is specified by 
children_size_return. This data is returned by the routine. 





DESCRIPTION 


QUERY TREE lists the parent, the children, and the number of children 
for a specified window. 


QUERY TREE lists the children in bottom-to-top stacking order. QUERY 
TREE returns a nonzero value if it completes successfully, and zero if it 
does not. 


To specify arguments that describe the child window identifiers returned 
by the routine, use children_return and num_children_return to 
access data owned by Xlib, or use children_size_return and 
children_buff_return to obtain a private copy of the data. To free the 
storage returned by this routine, use the display routine FREE. 





X ERRORS 
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VAX Cc Description 


X$C_BAD_WINDOW BadWindow A value that you specified for a window 
argument does not name a defined window. 


Window Routines 
RAISE WINDOW 


RAISE WINDOW 


Raises a window so that no sibling window obscures it. 





VAX FORMAT  X$RAISE_WINDOW (display, window_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XRaiseWindow (display, window_id) 


argument 

information XRaiseWindow (display, window_id) 
Display *display; 
Window window _id; 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


window_id 
The identifier of the window to be raised. The identifier of the specified 
window was originally returned by any CREATE WINDOW request. 





DESCRIPTION | RAISE WINDOW raises a window so that no sibling window obscures it. 
Raising a window does not change the x- and y-coordinates of the window. 


Raising a mapped window generates exposure events for that window and 
for any mapped subwindows that were obscured. 


If the override attribute of the window is false and another client has 
selected substructure redirect on the parent window, RAISE WINDOW 
generates a configure request event and performs no further processing. 





X ERRORS 


VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 


Window Routines 
RESIZE WINDOW 


RESIZE WINDOW 


Changes the size of a window. 





VAX FORMAT xX$RESIZE_WINDOW 
(display, window_id, width, height) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
width uns longword uns iongword read reference 
height uns longword uns longword read reference 





MIT CFORMAT XResizeWindow 
(display, window_id, width, height) 


argument 

information XResizeWindow(display, window_id, width, height) 
Display *display; 
Window window _id; 
unsigned int width, height; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 
The identifier of the window. The identifier of the window was originally 
returned by any CREATE WINDOW request. 


width 


The new width, in pixels, for the window. 


height 


The new height, in pixels, for the window. 





DESCRIPTION ~ RESIZE WINDOW changes the size of a specified window. 


The width and height define the inside area of the window, not including 
the window’s border. 
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Window Routines 
RESIZE WINDOW 


Changing the size of a mapped window can cause the window to lose its 
contents. If you decrease the size of a mapped window, exposure events 
are generated on any windows that were obscured. 


If the override attribute of the window is false and another client has 
selected Substructure Redirect on the parent window, RESIZE WINDOW 
generates a configure request event and performs no further processing. 


If you want to change the size of a window and move the window, use 
MOVE RESIZE WINDOW. 





X ERRORS 


VAX Cc Description 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Uniess a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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Window Routines 
RESTACK WINDOWS 


RESTACK WINDOWS 


Restacks an array of windows from top to bottom. 





VAX FORMAT X$RESTACK_WINDOWS 
(display, window_ids, num_windows) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_ids record uns longword read reference 
num_windows longword longword read reference 





MITC FORMAT XRestackWindows 
(display, window_ids, num_windows) 


argument 

information XRestackWindows (display, window_ids, num_windows) ; 
Display *display; 
Window window _ids[]; 
int num_windows; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _ids 
A pointer to an array of windows. Each element is the identifier of a 
window that will be restacked. The length of the array is specified by 
num_windows. 


num_windows 
The total number of window entries. This value specifies the number of 
elements in window_ids. 





DESCRIPTION  RESTACK WINDOWS restacks an array of windows from top to bottom. 
The stacking order of the first window in the array is unaffected, but all 
other windows in the array are stacked underneath it in the order of the 
array. 


All windows in the specified array must have a common parent. 
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Window Routines 
RESTACK WINDOWS 


If the override attribute of a window in the array is false and another 
client has selected substructure redirect on the parent window, RESTACK 
WINDOWS generates a Configure Request event for each array window 
that has an override attribute of false and performs no further processing. 





X ERRORS 


VAX Cc Description 
X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

* — An input-only window lacks this 
attribute. 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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Window Routines 
SET WINDOW BACKGROUND 


SET WINDOW BACKGROUND 


Sets the background of a specified window to the specified pixel. 





VAX FORMAT X$SET_WINDOW_BACKGROUND 
(display, window _id, pixel) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
pixel uns longword uns longword read reference 





MITC FORMAT XSetWindowBackground 
(display, window_id, pixel) 


argument 

information XSetWindowBackground (display, window_id, pixel) 
Display *display; 
Window window_id; 
unsigned long pixel; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window. The identifier of the window was originally 
returned by any CREATE WINDOW request. 


pixel 
The entry in the color map to be used for the window’s background. 





DESCRIPTION SET WINDOW BACKGROUND sets the background of a specified window 
to a specified pixel. SET WINDOW BACKGROUND uses the color map 
entry specified in pixel for the window’s background. 


SET WINDOW BACKGROUND PIXMAP can be performed only on an 
opaque window. An attempt to perform SET WINDOW BACKGROUND 
PIXMAP on an input-only window generates an error. 
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Window Routines 
SET WINDOW BACKGROUND 





X ERRORS 


VAX Cc Description 
X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

¢ An input-only window is used as a 
drawable. 

« One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

« — An input-only window lacks this 
attribute. 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 


Window Routines 
SET WINDOW BACKGROUND PIXMAP 


SET WINDOW BACKGROUND PIXMAP 


Changes the background tile of a specified window. 





VAX FORMAT X$SET_WINDOW_BACKGROUND_PIXMAP 
(display, window_id, background_pixmap_id) 


argument 


information Argument —~—~—*Usage_~—sData Type ==» Access. Mechanism — 


display identifier uns longword read reference 
window_id identifier uns longword read reference 
background_pixmap_id identifier uns longword read reference 





MITC FORMAT XSetWindowBackgroundPixmap 
(display, window_id, background_pixmap_id) 


argument 
information XSetWindowBackgroundPixmap (display, window_id, 
background_pixmap_id) 
Display *display; 
Window window_id; 
Pixmap background_pixmap_id; 








ARGUMENTS ~ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window that will have its background tile changed. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 


background_pixmap_id 
The identifier of the pixmap to be used as the background tile. 





DESCRIPTION SET WINDOW BACKGROUND PIXMAP changes the background tile of a 
specified window. 


SET WINDOW BACKGROUND PIXMAP uses the pixmap specified 

in background_pixmap_id as a background. If you do not specify 

a background pixmap, SET WINDOW BACKGROUND PIXMAP uses 
the background pixmap of the parent window. If you do not specify a 
background pixmap for the root window, SET WINDOW BACKGROUND 
PIXMAP restores the default background. 
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Window Routines 


SET WINDOW BACKGROUND PIXMAP 


SET WINDOW BACKGROUND PIXMAP does not repaint the background 
and does not change the current contents of the window. After you use 
SET WINDOW BACKGROUND PIXMAP, you can then clear and repaint 
the screen; this will not repaint the background you just set. 


The background pixmap can be freed immediately if no further explicit 
references to it are made. 


SET WINDOW BACKGROUND PIXMAP can be performed only on an 
opaque window. An attempt to perform SET WINDOW BACKGROUND 
PIXMAP on an input-only window generates a Bad Match error. 





X ERRORS 


VAX 
X$C_BAD_MATCH 


X$C_BAD_PIXMAP 


X$C_BAD_WINDOW 


Cc 
BadMatch 


BadPixmap 


BadWindow 


Description 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

An input-only window lacks this 
attribute. 


A value that you specified for a pixmap 
argument does not name a defined pixmap. 


A value that you specified for a window 
argument does not name a defined window. 
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Window Routines 
SET WINDOW BORDER 


SET WINDOW BORDER 


Sets a window's border to a specified pixel. 





VAX FORMAT X$SET_WINDOW_BORDER 
(display, window_id, pixel) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
pixel uns longword uns longword read reference 





MITC FORMAT XSetWindowBorder 
(display, window_id, pixel) 


argument 

information XSetWindowBorder (display, window_id, pixel) 
Display *display; 
Window window_id; 
unsigned long pixel; 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window for which the border is to be changed and 


repainted. The identifier of the window was originally specified by any 
CREATE WINDOW request. 


pixel 


The entry in the color map to be used for painting the border. 





DESCRIPTION SET WINDOW BORDER sets the border of a window to a specified pixel. 
SET WINDOW BORDER uses the color map entry specified in pixel for 
the window’s border. 


SET WINDOW BORDER cannot be performed on an input-only window; 
this generates a Bad Match error. 


To set the border tile of a window to a specified pixel, use SET WINDOW 
BORDER TILE. 
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X ERRORS 


X$C_BAD_MATCH 


X$C_BAD_WINDOW 


Description 


Possible causes are as follows: 


« In agraphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

* — An input-only window lacks this 
attribute. 


A value that you specified for a window 
argument does not name a defined window. 
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SET WINDOW BORDER PIXMAP 


Sets the border tile of a specified window. 





VAX FORMAT X$SET_WINDOW_BORDER_PIXMAP 
(display, window_id, border_pixmap_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
border_pixmap_id identifier uns longword read reference 





MITC FORMAT XSetWindowBorderPixmap 
(display, window_id, border_pixmap_id) 


argument 

information XSetWindowBorderPixmap (display, window_id, border _pixmap_id) 
Display *display; 
Window window_id; 
Pixmap border pixmap_ id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 

The identifier of the window that will have its border tile changed and 
repainted. The identifier of the window was originally returned by any 
CREATE WINDOW request. 


border_pixmap_id 
The identifier of the pixmap to be used as a background. 





DESCRIPTION SET WINDOW BORDER PIXMAP sets the border tile of a specified 
window. 


SET WINDOW BORDER PIXMAP uses the pixmap specified in 
border_pixmap_id for the border. SET WINDOW BORDER PIXMAP 
does not repaint the background; CLEAR can be used to repaint the 
background. 


The border pixmap can be freed immediately if no further explicit 
references to it are made. 
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SET WINDOW BORDER PIXMAP 


SET WINDOW BORDER PIXMAP can be performed only on an input 
output window that has a border. An attempt to perform SET WINDOW 
BORDER PIXMAP on an input-only window generates a Bad Match error. 


To set the border of a window to a specified pixel, use SET WINDOW 


BORDER. 





X ERRORS 
VAX Cc 


X$C_BAD_MATCH BadMatch 


X$C_BAD_PIXMAP BadPixmap 


X$C_BAD_VALUE BadValue 


X$C_BAD_WINDOW _ BadWindow 


Description 
Possible causes are as follows: 


« Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but fails 
to match in some other way required 
by the request. 

* — An input-only window lacks this 
attribute. 


A value that you specified for a pixmap 
argument does not name a defined pixmap. 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


A value that you specified for a window 
argument does not name a defined window. 
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SET WINDOW BORDER WIDTH 


Changes the border width of a window. 





VAX FORMAT X$SET_WINDOW_BORDER_WIDTH 
(display, window_id, width) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
width uns longword uns longword read reference 





MITC FORMAT XSetWindowBorderWidth 
(display, window_id, width) 


argument 

information XSetWindowBorderWidth (display, window_id, width) 
Display *display; 
Window window_id; 
unsigned int width; 





ARGUMENTS display 
The display information originally returned by OPEN DISPLAY. 
window _id 


The identifier of the window to be raised. The identifier of the window was 
originally returned by any CREATE WINDOW request. 


width 


The new width, in pixels, of the window border. 





DESCRIPTION SET WINDOW BORDER WIDTH changes the border of a window. 





X ERRORS 


VAX c Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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TRANSLATE COORDINATES 


Transfers coordinates from the coordinate space of one window to another 
window. 





VAX FORMAT _ boo/ = X$TRANSLATE_COORDINATES 
(display, src_window_id, dst_window_id, 
src_x_coord, src_y_coord [,dst_x_coord_return] 
[,dst_y_coord_return] [,child_id_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
bool longword longword write value 
display identifier uns longword read reference 
src_window_id identifier uns longword read reference 
dst_window_id identifier uns longword read reference 
src_xX_coord longword longword read reference 
src_y_coord longword longword read reference 
dst_x_coord_return longword longword write reference 
dst_y_coord_return longword longword write reference 
child_id_return identifier uns longword write reference 





MIT C FORMAT _boo/ = XTranslateCoordinates 
(display, src_window_id, dst_window_id, src_x_coord, 
src_y_coord, dst_x_coord_return, dst_y_coord_return, 
child_id_return) 


argument 
information int XTranslateCoordinates (display, src_window_id, dst_window_id, 
sre_x_ coord, srce_y coord, 
dst_x_coord_return, dst_y coord_return, 
child_id_return) 
Display *display; 
Window src_window_id, dst_window_id; 
int src_x_ coord, src_y coord; 
int *dst_x coord return, *dst_y coord return; 
Window *child_id_return; 
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RETURNS 


bool 

If TRANSLATE COORDINATES returns zero, this means that the source 
window and the destination window are on different screens, and that 
dst_x_coord and dst_y_coord are zero. If the destination coordinates are 
in a mapped child of the destination window, the identifier of that child 
window is returned in child_id_return. Otherwise, this argument is set 
to none. 





ARGUMENTS 
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display 
The display information originally returned by OPEN DISPLAY. 


src_window_id 
The identifier of the source window, which was originally returned by any 
CREATE WINDOW request. 


dst_window_id 


The identifier of the destination window. 


src_Xx_coord 

The x-coordinate of the source window. This coordinate is relative to the 
origin of the source window. The x- and y-coordinates define the upper left 
corner of the source window. 


src_y_coord 

The y-coordinate of the source window. This coordinate is relative to the 
origin of the source window. The x- and y-coordinates define the upper left 
corner of the source window. 


dst_x_coord_return 

The x-coordinate of the destination window. TRANSLATE COORDINATES 
returns the source coordinates relative to the origin of the source window 
to the dst_x_coord_return and dst_y_coord_return arguments, which 
are relative to the destination window’s origin. 


VAX only 
This argument is optional. 


dst_y_coord_return 

The y-coordinate of the destination window. TRANSLATE COORDINATES 
returns the source coordinates relative to the origin of the source window 
to the dst_x_coord_return and dst_y_coord_return arguments, which 
are relative to the destination window’s origin. 


VAX only 
This argument is optional. 


Window Routines 
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child_id_return 

If the destination coordinates are contained in a mapped child of the 
destination window, the identifier of that child window is returned in 
child_id_return. 


VAX only 
This argument is optional. 





DESCRIPTION TRANSLATE COORDINATES transfers coordinates from the coordinate 
space of one window to another window. Using TRANSLATE 
COORDINATES for this purpose frees the server from the need to perform 
this task. 





X ERRORS 


VAX Cc Description 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 
argument does not name a defined window. 
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UNMAP SUBWINDOWS 


Unmaps all subwindows of a specified window. 





VAX FORMAT X$UNMAP_SUBWINDOWS (display, window_id) 


argument 


information 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XUnmapSubwindows (display, window_id) 


argument 

information XUnmapSubwindows (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 

The identifier of the window for which all subwindows are to be unmapped. 
The identifier of the window was originally returned by any CREATE 
WINDOW request. 





DESCRIPTION UNMAP SUBWINDOWS unmaps all subwindows of a specified window, in 
bottom-to-top stacking order. 


UNMAP SUBWINDOWS generates an Unmap Window event on each 
subwindow and generates exposure events on windows that were obscured. 


When you want to unmap a single window, use UNMAP WINDOW. 





X ERRORS 
VAX Cc Description 
X$C_BAD_WINDOW _ BadWindow A value that you specified for a window 


argument does not name a defined window. 
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UNMAP WINDOW 


Unmaps a window. 





VAX FORMAT X$UNMAP_WINDOW (display, window_ia) 


argument 


information Argument Usage —~—‘dData Type —=—~—sAccess.-~=—Ss Mechanism 


display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XUnmapWindow (display, window_id) 


argument 

information XUnmapWindow (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 
The identifier of the window to be unmapped. The identifier of the window 
was originally returned by any CREATE WINDOW request. 





DESCRIPTION UNMAP WINDOW unmaps a window. 


When you unmap a window using UNMAP WINDOW, any subwindows of 
the specified window remain mapped, but they will not be visible until the 
parent window is mapped again. 


Unmapping a window generates exposure events on any windows that 
were obscured by the window and its children. UNMAP WINDOW also 
generates an Unmap Window event for the window specified in 
window_id, unless the server implements backing stores. 


If the specified window is already unmapped, UNMAP WINDOW has no 
effect. 


When you want to unmap all subwindows of a specified window, use 
UNMAP SUBWINDOWS. Using UNMAP SUBWINDOWS is much more 
efficient than using UNMAP WINDOW repeatedly. 
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UNMAP WINDOW 





X ERRORS 


VAX 
X$C_BAD_WINDOW 


Cc 
BadWindow 


Description 


A value that you specified for a window 
argument does not name a defined window. 
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An event is a report of either a change in the state of a device or the 
execution of a routine called by a client. 


The server reports events related to changes in the state of devices such 
as keyboards and pointers, changes in windows, graphics operations, client 
communications, and errors. Xlib maintains an event queue for each 
connection. The transport buffers events on a per-connection basis and 
delivers them to the Xlib event queues. An event may wait in a transport 
buffer until it is added to the appropriate Xlib event queues. It is therefore 
possible for an event to be available to a connection even though it has not 
yet been queued in the Xlib event queue. 


The event routines allow client programs to select the types of events that 
they want to be informed about and to manage event processing. 


The routines described in this chapter allow you to perform the following 
operations: 


° Select the event types to send to a window 
¢ Send an event to a window 

¢ Manipulate the event queue 

e Enable or disable synchronization 

¢ Handle I/O errors 

¢ Handle server errors 


e Return error messages 


For information on how to use the event routines, see the VMS 
DECwindows Xlib Programming Volume. 


The routines described in this chapter are listed in Table 4-1. 


Table 4-1 Event Routines 


Routine Name Description 


CHECK IF EVENT Checks the event queue for the event that 
you specify and flushes the output buffer if the 
event is not found. 


CHECK MASK EVENT Removes the next matching event from the 
queue. 
CHECK TYPED EVENT Returns the next event in the Xlib event queue 


that matches the event type. 


(continued on next page) 
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Table 4-1 (Cont.) Event Routines 


Routine Name 


CHECK TYPED WINDOW EVENT 


CHECK WINDOW EVENT 


EVENTS QUEUED 


FLUSH 


GET ERROR DATABASE TEXT 


GET ERROR TEXT 


GET MOTION EVENTS 


IF EVENT 


MASK EVENT 


NEXT EVENT 


PEEK EVENT 


PEEK IF EVENT 


PENDING 


PUT BACK EVENT 


SELECT ASYNC EVENT 


SELECT ASYNC INPUT 


SELECT INPUT 
SEND EVENT 


SET AFTER FUNCTION 


Description 


Returns the next matched event in the queue 
for the specified window. 


Removes the next matching event from the 
queue and returns immediately to indicate the 
status. 


Checks the number of events in the event 
queue. 

Flushes the Xlib output buffer for a client 
connection. 


Returns error messages from the error 
database. 


Returns a text string that describes the error 
code that you specify. 


Returns pointer motion events for a window 
based on the time coordinates that you supply. 


Checks the event queue for the event that 
you specify in the predicate procedure and 
removes the event if the events match. 


Removes the next matching event from the 
queue or blocks until a matching event is 
received. 


Gets the next event from the event queue, 
then removes the event. 


Peeks at and copies an event from the event 
queue. 


Checks the event queue for the event that you 
specify, but does not remove the event from 
the event queue. 


Returns the number of pending events. 


Copies an event back onto the head of the 
client’s Xlib event queue. 


Specifies an action routine and argument to be 
called when an event occurs. 


Specifies an action routine and arguments to 
be called when some subset of events occurs. 


Selects the event types to send to a window. 


Sends an event to a window without the 
window requesting the event. 


The synchronization handler to call before 
returning from an Xlib routine. 


(continued on next page) 
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Table 4-1 (Cont.) Event Routines 


Routine Name Description 

SET ERROR HANDLER A user-written nonfatal error handler to be 
called when an XError event is received. 

SET lO ERROR HANDLER A user-written routine to handle fatal 1/O 
errors. 

SYNC Flushes the client's Xlib output buffer and 


waits for all requests to be received and 
processed by the server. 


SYNCHRONIZE Enables or disables synchronization for a 
display and returns the status of the previous 
state. 

WINDOW EVENT Removes the next matching event from the 


queue for the specifed window. 





4.1 Event Data Structure 


The event data structure is a union of structures that stores values for 
input event attributes. Client programs can use the event mask to select 
the input event attributes for which they receive notification. 


Note: See the VMS DECwindows Xlib Programming Volume for a 
complete description of the structures that form the event data 
structure. The VMS DECwindows Xlib Programming Volume 
includes descriptions of the structure members for both the VAX 
binding and the MIT C binding. 


The VAX binding event structure is shown in Figure 4-1. 
Figure 4-1 Event Data Structure (VAX Binding) 


x$l_evnt_type 0 
variable event data, depending upon x$l_evnt_type (124 bytes) 
| fs 


The members of the structures that comprise the VAX binding event 
data structure are described in the VMS DECwindows Guide to Xlib 
Programming: VAX Binding. 





The MIT C binding event structure is shown in Figure 4—2. 
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4.1 Event Data Structure 


Figure 4-2 Event Data Structure (MIT C Binding) 





typedef union _XEvent { 
int type; 
XAnyEvent xany; 
XKeyEvent xkey; 
XButtonEvent xbutton; 
XMotionEvent xmotion; 
XCrossingEvent xcrossing; 
XFocusChangeEvent xfocus; 
XExposeEvent xexpose; 
XGraphicsExposeEvent xgraphicsexpose; 
XNOExposeEvent xnoexpose; 
XVisibilityEvent xvisibility; 
XCreateWindowEvent xcreatewindow; 
XDestroyWindowEvent xdestroywindow; 
XUnmapEvent xunmap; 
XMapEvent xmap; 
XMapRequestEvent xmaprequest; 
XReparentEvent xreparent; 
XConfigureEvent xconfigure; 
XGravityEvent xgravity; 
XResizeRequestEvent xresizerequest; 
XConfigureRequestEvent xconfigurerequest; 
XCirculateEvent xcirculate; 
XCirculateRequestEvent xcirculaterequest; 
XPropertyEvent xproperty; 
XSelectionClearEvent xselectionclear; 
XSelectionRequestEvent xselectionrequest; 
XSelectionEvent xselection; 
XColormapEvent xcolormap; 
XClientMessageEvent xclient; 
XMappingEvent xmapping; 
XErrorEvent xerror; 
XKeymapEvent xkeymap; 
long pad[24]; 

} XEvent; 





The members of the structures that comprise the MIT C binding event 
data structure are described in the VMS DECwindows Guide to Xlib 
Programming: MIT C Binding. 





The Event Mask 


The event routines require that you use the event_mask argument to 
define the events for which a client receives notice. To do this, you pass an 
event mask to an Xlib event-handling function that takes an event_mask 
argument. The event mask name describes the events that you want the 
server to return to the client. 


Table 4—2 lists the elements of the event mask and their descriptions. 


Table 4-2 Event Mask Elements 


Bit 
1 


2 
3 


22 


23 
24 
25 


VAX Value 


X$M_KEY_PRESS 
X$M_KEY_RELEASE 
X$M_BUTTON_PRESS 


X$M_BUTTON_RELEASE 
X$M_ENTER_WINDOW 


X$M_LEAVE_WINDOW 


X$M_POINTER_MOTION 
X$M_POINTER_MOTION_HINT 
X$M_BUTTON1_MOTION 


X$M_BUTTON2_MOTION 
X$M_BUTTON3_MOTION 
X$M_BUTTON4_MOTION 
X$M_BUTTON5_MOTION 
X$M_BUTTON_MOTION 
X$M_KEYMAP_STATE 


X$M_EXPOSURE 
X$M_VISIBILITY_CHANGE 
X$M_STRUCTURE_NOTIFY 


X$M_RESIZE_REDIRECT 
X$M_SUBSTRUCTURE_NOTIFY 


X$M_SUBSTRUCTURE _ 
REDIRECT 


X$M_FOCUS_CHANGE 


X$M_PROPERTY_CHANGE 
X$M_COLORMAP_CHANGE 
X$M_OWNER_GRAB_BUTTON 


MIT C Value 


KeyPressMask 
KeyReleaseMask 
ButtonPressMask 


ButtonReleaseMask 
EnterWindowMask 


LeaveWindowMask 


PointerMotionMask 
PointerMotionHintMask 
Button1 MotionMask 


Button2MotionMask 
Button3MotionMask 
Buiton4MotionMask 
Button5MotionMask 
ButtonMotionMask 
KeymapStateMask 


ExposureMask 
VisibilityChangeMask 
StructureNotifyMask 


ResizeRedirectMask 
SubstructureNotifyMask 
SubstructureRedirectMask 


FocusChangeMask 


PropertyChangeMask 
ColormapChangeMask 
OwnerGrabButtonMask 


Event Routines 
4.2 The Event Mask 


Description 


Keyboard down events wanted 
Keyboard up events wanted 


Pointer button down events 
wanted 


Pointer button up events wanted 


Pointerwindow entry evenis 
wanted 


Pointerwindow leave events 
wanted 


Pointer motion events wanted 
Pointer motion hints wanted 


Pointer motion while button 1 
down 


Pointer motion while button 2 
down 


Pointer motion while button 3 
down 


Pointer motion while button 4 
down 


Pointer motion while button 5 
down 


Pointer motion while any button 
down 


Keyboard state wanted at 
window entry and focus in 


Any exposure wanted 
Any change in visibility wanted 


Any change in window structure 
wanted 


Redirect resize of this window 
Substructure notification wanted 
Redirect substructure of window 


Any change in input focus 
wanted 


Any change in property wanted 
Any change in color map wanted 


Automatic grabs should activate 
with owner_events set to true 


You can also specify X¥$M_NO_EVENT or NoEventMask in event_mask 
to indicate that no events are wanted. 
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The Predicate Procedure 


Xlib provides routines that allow you to see if the next event on the Xlib 
event queue is the one that your client program wants. These routines 
require you to provide a predicate procedure, which determines if the next 
event in the queue matches the one your client program wants. 


Your predicate procedure must decide only if the event is useful (for 
example, by checking the type member of the event data structure) and 
must not call Xlib routines. Xlib routines lock the event queue when they 
access it; the predicate procedure is called from within an Xlib routine and 
must not attempt to lock the queue itself. 


The format of the predicate procedure in the MIT C binding is as follows: 


Bool (*predicate) (display, event, args) 
Display *display; 
XEvent *event; 
char *args; 


The arguments of the predicate procedure are defined as follows: 


display A pointer to the display data structure for which you want to check 
the input event queue. OPEN DISPLAY returned a pointer to the 
display structure when it opened the display. 

event A pointer to the event data structure. The event data structure is a 
union of the individual structures declared for each event type. 


args A pointer to the arguments passed in from IF EVENT, CHECK IF 
EVENT, or PEEK IF EVENT. 


The predicate procedure should return a nonzero (true) or zero (false) 
value to indicate if the event is the one that should be returned. Xlib calls 
the predicate procedure once for each event in the queue until it finds 

a match between the event in the queue and the event specified by the 
corresponding routine. 


Time Coordinate Data Structure 


The time coordinate data structure defines the data structure that is 
returned by the GET MOTION EVENTS routine. 


The VAX binding time coordinate data structure is shown in Figure 4-3. 
Figure 4-3 Time Coordinate Data Structure (VAX Binding) 






x$l_timce_time 0 


The members of the VAX binding time coordinate structure are described 
in Table 4-3. 
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Table 4-3 Members of the Time Coordinate Data Structure (VAX 


Binding) 
Member Name Contents 
X$C_TIMC_TIME Set to the time, in milliseconds 
X$C_TIMC_X Set to the x-coordinate of the pointer cursor 


and is reported relative to the origin of the 
specified window 

X$C_TIMC_Y Set to the y-coordinate of the pointer cursor 
and is reported relative to the origin of the 
specified window 


The MIT C binding time coordinate data structure is shown in 
Figure 4-4, 


Figure 4-4 Time Coordinate Data Structure (MIT C Binding) 


typedef struct XTimeCoord { 
Time time; 
short x, y; 
} XTimeCoord; 


The members of the MIT C binding time coordinate structure are described 
in Table 4-4. 


Table 4-4 Members of the Time Coordinate Data Structure (MIT C 


Binding) 
Member Name Contents 
time Set to the time, in milliseconds 
x Set to the x-coordinate of the pointer cursor 
and are reported relative to the origin of the 
specified window 
y Set to the y-coordinate of the pointer cursor 


and are reported relative to the origin of the 
specified window 





There are two default Xlib error handlers: one to handle typically 

fatal conditions, such as losing the connection to a display, and one to 
handle error events from the server. The default error handlers print an 
explanatory message and exit. You can substitute your own user-written 
error handling routines for the default error handlers at any time. If 
either of the error handling routines (SET ERROR HANDLER or SET IO 
ERROR HANDLER) is passed a null pointer, Xlib reinvokes the default 
error handler. 
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Xlib calls the default or user-written error handler whenever an error 
event is received. The error event is assumed to be nonfatal, and it is 
acceptable for the error handler to generate a return. The error handler 
should not perform any operations, either directly or indirectly, on the 


display. 


The Xlib routines can return the error codes described in Table 4—5. 


Table 4—5 Xlib Error Codes 


VAX 
X$C_BAD_ACCESS 


X$C_BAD_ALLOC 
X$C_BAD_ATOM 
X$C_BAD_COLOR 
X$C_BAD_CURSOR 
X$C_BAD_ 
DRAWABLE 
X$C_BAD_FONT 


X$C_BAD_GC 


X$C_BAD_{D_ 
CHOICE 


X$C_BAD_ 
IMPLEMENTATION 


MIT C 


BadAccess 


BadAlloc 
BadAtom 
BadColor 
BadCursor 
BadDrawable 
BadFont 
BadGC 


BadIDChoice 


Badimplementation 


Description 


Possible causes are as follows: 


* An attempt to grab a key/button combination that has 
already been grabbed by another client 

* An attempt to free a color map entry that was not allocated 
by the client 

« An attempt to store in a read-only or unallocated color map 
entry 

+ An attempt to modify the access control list from other than 
the local host 

* An attempt to select an event type that at most one client 
can select at a time, when another client has already 
selected it 


The server did not allocate the requested resource for any 
cause. 


The value that you specified in an atom argument does not 
name a defined atom. 


A value that you specified for a color map argument does not 
name a defined color map. 


A value that you specified for a cursor argument does not name 
a defined cursor. 


A value that you specified for a drawable argument does not 
name a defined window or pixmap. 


A value that you specified for a font argument does not name a 
defined font (or, in some cases, graphics context). 


A value that you specified for a graphics context argument does 
not name a defined graphics context. 


The value that you chose for a resource identifier is either not 
included in the range assigned to the client, or it is already in 
use. Under normal circumstances this cannot occur and should 
be considered a server or Xlib error. 


The server does not implement some aspect of the request. 
This error is most likely caused by a server extension; a server 
that generates this error for a core protocol request is deficient. 
As such, this error is not listed for any particular request. Client 
programs should be prepared to receive this type of error and 
either handle or discard it. 
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Table 4-5 (Cont.) Xlib Error Codes 
VAX MIT C Description 





X$C_BAD_LENGTH BadLength The length of a request is shorter or longer than required to 
minimally contain the arguments. This error usually indicates an 
internal Xlib or server error. The length of a request exceeds the 
maximum length accepted by the server. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« In a graphics request, the root and depth of the graphics 
context do not match those of the drawable. 
* An input-only window is used as a drawable. 


* One argument or pair of arguments has the correct type 
and range but fails to match in some other way required by 
the request. 


* — An input-only window lacks this attribute. 


X$C_BAD_NAME BadName The font or color that you specified does not exist. 

X$C_BAD_PIXMAP BadPixmap A value that you specified for a pixmap argument does not name 
a defined pixmap. 

X$C_BAD_REQUEST BadRequest The major or minor opcode that you specified does not indicate 


a valid request. This is usually an Xlib or server error. 


X$C_BAD_ VALUE BadValue Some numeric values fall outside the range of values accepted 
by the request. Unless a specific range is specified for an 
argument, the full range defined by the argument’s type is 
accepted. Any argument defined as a set of alternatives can 
generate this error. 


X$C_BAD_WINDOW _ BadWindow A value that you specified for a Window argument does not 
name a defined window. 





Note: The Bad Atom, Bad Color, Bad Cursor, Bad Drawable, Bad Font, 
Bad Pixmap, and Bad Window errors are also used when the 
argument type is extended by a set of fixed alternatives. 


Error Event Data Structure 


The error event data structure defines the format of errors reported to the 
default or user-supplied error handlers. 


The VAX binding error event data structure is shown in Figure 4—5. 
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Event Routines 


4.6 Error Event Data Structure 


Figure 4-5 Error Event Data Structure (VAX Binding) 
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x$b_erev_minor_code x$b_erev_request_code x$b_erev_error_code 


The members of the VAX binding error event data structure are described 
in Table 4-6. 





Table 4-6 Members of the Error Event Data Structure (VAX Binding) 


Member Name Contents 

X$L_EREV_TYPE The type of eveni. 

X$A_EREV_DISPLAY The display information originally returned by 
OPEN DISPLAY. 

X$L_EREV_RESOURCE_ID The resource identifier associated with the 
error. 

X$L_EREV_SERIAL The serial number of the request processed by 


the server immediately before the failing call 
was made. Xlib and the server use the serial 
number to identify the protocol request that 
caused the error. 


X$B_EREV_ERROR_CODE The error code of the failed request. The error 
codes are described in Table 4-5. 

X$B_EREV_REQUEST_CODE The major operation code of the failed request. 

X$B_EREV_MINOR_CODE The minor operation code of the failed request. 





The MIT C binding error event data structure is shown in Figure 4-6. 
Figure 4-6 Error Event Data Structure (MIT C Binding) 





typedef struct XErrorEvent { 
int type; 
Display *display; 
XID resourceid; 
unsigned long serial; 
unsigned char error_code; 
unsigned char request_code; 
unsigned char minor code; 
}XErrorEvent; 





Event Routines 
4.6 Error Event Data Structure 


The members of the MIT C binding error event data structure are 
described in Table 4—7. 


Table 4-7 Members of the Error Event Data Structure (MIT C Binding) 


Member Name Contents 

type The type of event. 

display The display information originally returned by 
OPEN DISPLAY. 

resourceid The resource identifier associated with the 
error. 

serial The serial number of the request processed by 


the server immediately before the failing call 
was made. Xlib and the server use the serial 
number to identify the protocol! request that 
caused the error. 


error_code The error code of the failed request. The error 
codes are described in Table 4—5. 

request_code The major operation code of the failed request. 

minor_code The minor operation code of the failed request. 





4.7 Event Routines 


The following pages describe the Xlib event routines. 
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CHECK IF EVENT 


CHECK IF EVENT 


Checks the event queue for the event that you specify in the predicate 
procedure and flushes the output buffer if the event is not found. 





VAX FORMAT __ present_return = X$CHECK_IF_EVENT 
(display, event_return, predicate, arg) 


argument 

information Argument Usage Data Type Access Mechanism 
present_return Boolean longword write value 
display identifier uns longword read reference 
event_return record xSevent write reference 
predicate procedure proc entry mask _ read reference 
arg longword uns longword read value 





MIT C FORMAT _present_return = XChecklfEvent 
(display, event_return, predicate, arg) 





argument 
information Bool XCheckifEvent (display, event_return, predicate, arg) 
Display *display; 
xXEvent *event_return; 
Bool (*predicate) (); 
char *arg; 
RETURNS present_return 


A Boolean value that specifies whether the routine completed successfully. 
When the value of present_return is zero, no matching events were 
found. When the value of present_return is one (1), a matching event 
was found. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_return 

A pointer to the event structure to which the matching event is returned. 
CHECK IF EVENT copies the matched event’s associated structure into 
this client-supplied structure. The event data structure is shown in 
Section 4.1. 


Event Routines 
CHECK IF EVENT 


predicate 

A pointer to a user-supplied procedure that determines if the next event 
in the event queue matches the event you specify in the args argument. 
When true, predicate returns a nonzero value. When false, predicate 
returns zero. Xlib calls the predicate procedure once for each event in the 
queue until it returns true. 


For more information about the predicate procedure see Section 4.3. 


arg 
The user-specified arguments that are passed to the predicate procedure. 





DESCRIPTION 


CHECK IF EVENT returns true when the specified predicate procedure 
returns true for the next event in the queue that matches the specified 
event. If the predicate procedure finds a match, CHECK IF EVENT copies 
the matched event into the client-supplied event structure and returns 
true. The event is removed from the queue. All earlier events in the 
queue are not discarded. 


If the predicate procedure finds no match, CHECK IF EVENT returns 
false and flushes the output buffer. CHECK IF EVENT does not block. 


The event data structure is shown in Section 4.1. 
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CHECK MASK EVENT 


Removes the next matching event from the queue and immediately returns a 
value to indicate the status. 





VAX FORMAT __ present_return = X$CHECK_MASK_EVENT 
(display, event_ mask, event_return) 


argument 

information Argument Usage Data Type Access Mechanism 
present_return Boolean longword write value 
display identifier uns longword read reference 
event_mask mask_longword longword read reference 
event_return record x$event write reference 





MIT C FORMAT _present_return = XCheckMaskEvent 
(display, event_mask, event_return) 





argument 

information Bool XCheckMaskEvent (display, event_mask, event_return) 
Display *display; 
long event_mask; 
XEvent *event_return; 

RETURNS present_return 


A Boolean value that specifies whether the routine completed successfully. 
When present_return is false, no matching events were found. When 
present_return is true, a matching event was found. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_mask 

A bitmask that specifies the event types for which you want to remove 
an event. The mask is an inclusive OR of one or more of the event mask 
elements described in Table 4—2. 


event_return 

A pointer to an event structure to which the matching event is returned. 
CHECK MASK EVENT copies the matched event’s associated data 
structure into this client-supplied data structure. The event data structure 
is shown in Section 4.1. 


Event Routines 
CHECK MASK EVENT 





DESCRIPTION 


CHECK MASK EVENT searches the event queue, and the server 
connection, for the event that matches the specified mask. If it finds a 
match, CHECK MASK EVENT removes the event, copies it into an event 
structure supplied by the caller and returns true. Earlier events in the 
queue are not discarded. 


If no matching event has been queued, CHECK MASK EVENT flushes the 
client’s output buffer and returns false. 


Note that CHECK MASK EVENT differs from MASK EVENT in that 
CHECK MASK EVENT returns immediately while MASK EVENT blocks 
until a match is found. CHECK MASK EVENT also returns a Boolean 
value indicating if the event was returned. 


The event data structure is shown in Section 4.1. 
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CHECK TYPED EVENT 


Returns and removes the next event in the event queue that matches the 
event type. 





VAX FORMAT _ present_return = X$CHECK_TYPED_EVENT 
(display, event_type, event_return) 


argument 

information Argument Usage Data Type Access Mechanism 
present_return Boolean longword write value 
display identifier uns longword read reference 
event_type longword longword read reference 
event_return record x$event write reference 





MIT C FORMAT present_return = XCheckTypedEvent 
(display, event_type, event_return) 





argument 

information Bool XCheckTypedEvent (display, event_type, event_return) 
Display *display; 
int event_type; 
XEvent *event_return; 

RETURNS present_return 


A Boolean value that specifies whether the routine completed successfully. 
When the value of present_return is false, no matching events were 
found. When the value of present_return is true, a matching event was 
found. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_type 
The event type to be compared. 


event_return 

A pointer to an event structure to which the matching event is returned. 
CHECK TYPED EVENT copies the matched event’s associated structure 
into this client-supplied structure. 


DESCRIPTION 


Event Routines 
CHECK TYPED EVENT 





CHECK TYPED EVENT searches the event queue for the first event that 
matches the specified event type. If CHECK TYPED EVENT does not find 
a match, Xlib searches the available events for the connection that have 
yet to be queued. If CHECK TYPED EVENT finds a match, it removes the 
event, copies the associated event structure to the event structure specified 


by event_return, and returns true. Earlier events in the queue are not 
discarded. 


If no match is found, CHECK TYPED EVENT flushes the output buffer 
and returns false. 
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CHECK TYPED WINDOW EVENT 


Returns the next matching event in the queue for the specified window. 





VAX FORMAT _ present_return = X$CHECK_TYPED_WINDOW_EVENT 
(display, window_id, event_type, event_return) 


argument 

information Argument Usage Data Type Access Mechanism 
present_return Boolean longword write value 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
event_type longword longword read reference 
event_return record x$event write reference 





MIT C FORMAT present_return = XCheckTypedWindowEvent 
(display, window_id, event_type, event_return) 





argument 
information Bool XCheckTypedWindowEvent (display, window_id, event_type, 
event _return) 
Display *display; 
Window window_id; 
int event_type; 
XEvent *event return; 
RETURNS present_return 


A Boolean value that specifies whether the routine completed successfully. 
When the value of present_return is false, no matching events were 
found. When the value of present_return is true, a matching event was 
found. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The window identifier for which you want to check the typed event. 


even t type 
The event type to be compared. 
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CHECK TYPED WINDOW EVENT 


event_return 

A pointer to an event structure to which the matching event is returned. 
CHECK TYPED WINDOW EVENT returns the matched event’s associated 
structure into this client-supplied structure. 





DESCRIPTION 


CHECK TYPED WINDOW EVENT searches the event queue for the 
events associated with the specified type and window. If CHECK TYPED 
WINDOW EVENT does not find a match, Xlib searches the available 
events for the connection that have yet to be queued. If it finds a match, 
CHECK TYPED WINDOW EVENT removes the event from the queue, 
copies it into the event data structure specified by event_return, and 
returns true. Earlier events in the queue are not discarded. If no match is 
found, CHECK TYPED WINDOW EVENT flushes the output buffer and 
returns false. 
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CHECK WINDOW EVENT 


Removes the next matching event from the queue and indicates status. 





VAX FORMAT __ present_return = X$CHECK_WINDOW_EVENT 
(display, window_id, event_mask, event_return) 


argument 

information Argument Usage Data Type Access Mechanism 
present_return Boolean longword write value 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
event_mask mask_longword uns longword read reference 
event_return record x$event write reference 





MIT C FORMAT present_return = KCheckWindowEvent 
(display, window_id, event_mask, event_return) 





argument 
information Bool XCheckWindowEvent (display, window_id, event_mask, 
event_return) 
Display *display; 
Window window_id; 
long event_mask; 
XEvent *event_return; 
RETURNS present_return 


A Boolean Value that specifies whether the routine completed successfully, 
When the value of present_return is false, no matching events were 
found. When the value of present_return is true, a matching event was 
found. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 
The identifier of the window for which you want to remove the event from 
the event queue. 


Ff 
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CHECK WINDOW EVENT 


event_mask 

A bitmask that specifies the events types for which you want to remove 
an event. This mask is an inclusive OR of one or more of the event mask 
elements described in Table 42. 


event_return 

A pointer to an event structure to which the matching event is returned. 
CHECK WINDOW EVENT copies the matched event’s associated structure 
to this client-supplied structure. The event data structure is shown in 
Section 4.1. 





DESCRIPTION 


CHECK WINDOW EVENT searches the event queue for the next event 
that matches both window_id and event_mask. If CHECK WINDOW 
EVENT does not find a match, Xlib searches the available events for the 
connections that have yet to be queued. 


If it finds a match, CHECK WINDOW EVENT removes the event, copies 
it into the event structure specified in event_return, and returns true. 
Earlier events on the queue are not discarded. If no matching event is 
found, CHECK WINDOW EVENT flushes the output buffer and returns 
false. 


Note that CHECK WINDOW EVENT differs from WINDOW EVENT in 
that CHECK WINDOW EVENT returns immediately while WINDOW 
EVENT blocks until a match is found. 


The event data structure is shown in Section 4.1. 
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EVENTS QUEUED 


Checks the number of events in the event queue. 





VAX FORMAT ~~ count=X$EVENTS_QUEUED (display, mode) 


argument 

information Argument Usage Data Type Access Mechanism 
count longword longword write value 
display identifier uns longword read reference 
mode longword longword read reference 





MITC FORMAT count = XEventsQueued (display, mode) 





argument 

information int XEventQueued(display, mode) 
Display *display; 
int mode; 

RETURNS count 


The number of events in the event queue. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


mode 
The mode by which you want to return the number of queued events. The 
predefined values for mode are as follows: 


VAX MIT C 
X$C_QUEUED_ALREADY QueuedAlready 


X$C_QUEUED_AFTER_ QueuedAfterFlush 
FLUSH 

X$C_QUEUED_AFTER_ QueuedAfterReading 
READING 


Event Routines 
EVENTS QUEUED 


Description 


Returns the number of 
events already in the queue. 


Returns the number of 
events already in the queue, 
if it is nonzero. If there are 
no events in the queue, it 
flushes the output buffer, 
attempts to read more 
events for the applications’s 
connection, and returns the 
number read. 


Returns the number of 
events already in the queue, 
if it is nonzero. If there are 
no events in the queue, 

it attempts to read more 
events for the applications’s 
connection, without flushing 
the output buffer, and returns 
the number read. 





DESCRIPTION 


EVENTS QUEUED checks the number of events in the event queue, 
including those that have yet to be queued. Xlib maintains an event queue 
for each connection. The transport buffers events on a per-connection 
basis and delivers them to the Xlib event queues. An event may wait in 

a transport buffer until it is added to the appropriate Xlib event queues. 
It is therefore possible for an event to be available to a connection even 
though it has not yet been queued in the Xlib event queue. 


EVENTS QUEUED always returns immediately without I/O if there 

are events in the queue. EVENTS QUEUED with a mode of Queued 
After Flush is identical to PENDING. EVENTS QUEUED with a mode of 
Queued Already is identical to the Q LENGTH display routine. 
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FLUSH 


Flushes the Xlib output buffer for a client connection. 





VAXFORMAT X$FLUSH (display) 


argument 


information Argument Usage —-DataType =— Access. ~=—Ss Mechanism 


display identifier uns longword read reference 





MITC FORMAT XFlush (display) 


argument 


information eee) ee tay) 
Display *display; 





ARGUMENT _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION _ FLUSH flushes all output requests that have been buffered in the client 
output buffer but have not yet been sent to the server. Because flushing is 
done as needed, the next time the client calls PENDING, NEXT EVENT, 
or WINDOW EVENT, most client programs do not need to call the FLUSH 
routine. 


Event Routines 
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GET ERROR DATABASE TEXT 


Returns error messages from the error database. 





VAX FORMAT X$GET_ERROR_DATABASE_TEXT 
(display, app|_name, message_name, 
default_message_name, buff_return [,length]) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
appl_name char string character string read descriptor 
message_name char string character string read descriptor 
default_message_ _—_— char string character string read descriptor 
name 
buff_return char string character string write descriptor 
length word uns word write reference 





MIT C FORMAT XGetErrorDatabaseText 
(display, app|_name, message_name, 
default_message_name, buff_return, length) 


argument 

information XGetErrorDatabaseText (display, appl_name, message_name, 
default_message_ name, buff _return, 
length) 


Display *display; 

char *appl_name, *message name; 
char *default_message_name; 
char *buff_return; 

int length; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


applI_name 
The name of the application for which you want to obtain error messages. 
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GET ERROR DATABASE TEXT 


message_name 
The type of the error message that you want. Xlib uses the following 
message types to report errors: 


VAX Binding MIT C Binding _ Description 
X$C_PROTO_ERROR  XProtoError The protocol error number is used as a 


string for message_name. 


X$C_XLIB_MESSAGE _ XlibMessage These are the message strings that are 
used internally by Xlib. 


X$C_REQUEST XRequest The major protocol request number is 
used for the message argument. If no 
string is found in the error database, the 
default string is returned to buff_return. 


VAX only 


The message_name argument is the address of a character string 
descriptor that points to the string. 


MIT C only 


The message_name argument is a pointer to the null-terminated 
character string. 


default_message_name 


The default error message if no message is found in the database. 


buff_return 


The error message. 


length 
The size of the buffer that is passed in buff_return. 


VAX only 
This argument is optional. 





DESCRIPTION 
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GET ERROR DATABASE TEXT returns a message (or the default 
message) from the error message database. Xlib uses this function 
internally to look up error messages. 


Event Routines 
GET ERROR TEXT 


GET ERROR TEXT 


Returns a text string that describes the error code that you specify. 





VAX FORMAT X$GET_ERROR_TEXT 
(display, code, buff_return [,len_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
code longword longword read reference 
buff_return char string character string write descriptor 
len_return longword uns longword write reference 





MITC FORMAT XGetErrorText 
(display, code, buff_return, length) 


argument 
information XGetErrorText (display, code, buff return, length) 
Display *display; 
int code; 
char *buff_return; 
int length; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


code 
The error code for which you want to obtain a textual description. 
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GET ERROR TEXT 


DESCRIPTION 
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buff_return 
A pointer to the buffer to which GET ERROR TEXT returns the 
description. 


VAX only 


The buff_return argument is the address of a character string descriptor 
that points to the string. 


MIT C only 
The buff_return argument is a pointer to a client-allocated buffer. 
len_return (VAX only) 


The size of the text string that GET ERROR TEXT returns. This 
argument is optional in the VAX binding. 


length (MIT C only) 
The size of the buff_return buffer. 





GET ERROR TEXT returns a textual description of the error code that you 
specify. You should use this routine to obtain an error description because 
extensions to Xlib can define their own error codes and strings. 
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GET MOTION EVENTS 


Returns pointing device motion events for a window based on the time 
coordinates that you supply. 





VAX FORMAT _ status_return = X$GET_MOTION_EVENTS 
(display, window_id, start, stop, num_events_return 
[time_return] [,time_size] [, time _buff_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return cond_value uns longword write value 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
start longword uns longword read reference 
stop longword uns longword read reference 
num_events_return longword longword write reference 
time_return address uns longword write reference 
time_size longword longword read reference 
time_buff_return array uns longword write reference 





MIT C FORMAT _timecoord_return = XGetMotionEvents 
(display, window_id, start, stop, num_events_return) 


argument 
information XTimeCoord *XGetMotionEvents (display, window_id, start, stop, 
num_events_return) 
Display *display; 
Window window_id; 
Time start, stop; 
int *num_events return; 





RETURNS status_return (VAX only) 
Possible status values returned by the VAX binding are as follows: 


Value Description 


X$_ERRORREPLY An error was received from the server. 
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GET MOTION EVENTS 


Value Description 

X$_TRUNCATED The user buffer specified in time_buff_return was not large 
enough. 

SS$_NORMAL The routine completed successfully. 


timecoord_return (MIT C only) 

All the events in the motion history buffer that fall within the specified 
starting and stopping times (inclusive), and that have coordinates that lie 
within the specified window (including borders) at its current placement, 
are returned. 


If the starting time is later than the stopping time, or if the starting time 
is in the future, no events are returned. 


The time coordinate data structure is shown in Section 4.4. 





ARGUMENTS 
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display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window for which you want to receive motion events. 


start 

The beginning of the time interval, in milliseconds, for which the events 
are returned from the motion history buffer. You can pass a time- 
stamping, expressed in milliseconds, or the predefined values 
X$C_CURRENT_TIME or CurrentTime. If the stopping time is in the 
future, it is equivalent to specifying Current Time. 


stop 

The end of the time interval, in milliseconds, for which the events are 
returned from the motion history buffer. You can pass a time-stamping, 
expressed in milliseconds, or the predefined values X$C_CURRENT_TIME 
or CurrentTime. If the stopping time is in the future, it is equivalent to 
specifying Current Time. 


num_events_r eturn 
A pointer to the number of events returned from the motion history buffer. 


time_return (VAX only) 

The address of the time coordinate data structure. This argument is 
optional. You can specify either time_return to receive the address of the 
time coordinate data structure, or the time_size and time_buff_return 
arguments to receive an array of time coordinates in a buffer. 


time_size (VAX only) 
The length of the time coordinate buffer. This argument is optional. 


time_buff_return (VAX only) 
A pointer to an array of time coordinates. The length of the array is 
specified by time_size. This argument is optional. 


Event Routines 
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DESCRIPTION 


Note: 


GET MOTION EVENTS returns a pointer to all of the events in the 
pointing device motion history queue that fall between the starting and 
stopping times (inclusive) that you specify and that have coordinates 
that lie within (including borders) the specified window at its present 
placement. 


If the starting time is later that the stopping time, or if the starting time 
is in the future, no events are returned. If the stopping time is in the 
future, it is equivalent to specifying the predefined value Current Time, 
which is reserved for use in requests to represent the current server time. 


GET MOTION EVENTS does not request notification of pointing device 
motion history events from the Xlib input event queue; it receives this 
information in the form of a reply directly from the server. 


The time coordinate data structure is shown in Section 4.4. 


The time member of the time coordinate data structure is set to the time 
in milliseconds. The x and y members are set to the coordinates of the 
pointer and are reported relative to the origin of the specified window. 


Clients should use FREE to free the data that is returned from this call. 


Some XII server implementations maintain a history of pointer 
motion by storing the pointer position at each pointer hardware 
interrupt in a motion history buffer. GET MOTION EVENTS 
returns a pointer to the events in the motion history buffer. The 
VMS DECwindows server does not support the motion history 
buffer. 





X ERRORS 


VAX MIT C Description 


X$C_BAD_WINDOW  BadWindow A value that you specified for a window 
argument does not name a defined window. 


Event Routines 
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IF EVENT 


Checks the input event queue for the event that you specify in the predicate 
procedure, and removes the event from the queue if the events match. 





VAX FORMAT X$IF_EVENT 
(display, event_return, predicate, arg) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
event_return record x$event write reference 
predicate procedure proc entry mask read reference 
arg longword uns longword read value 





MITC FORMAT XifEvent 
(display, event_return, predicate, arg) 


argument 
information XIifEvent (display, event _return, predicate, arg) 
Display *display; 
XEvent *event_return; 
Bool (*predicate) (); 
char *arg; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_r eturn 

A pointer to the event structure to which the matching event is returned. 
IF EVENT copies the matched event’s associated structure into this client- 
supplied structure. The event data structure is shown in Section 4.1. 


predicate 

A pointer to a user-supplied procedure that determines if the next event 
in the event queue matches the event you specify in the arg argument. 
When true, predicate returns a nonzero value. When false, predicate 
returns zero. You call the predicate procedure once for each event in the 
queue until it returns a nonzero value. 


For more information about the predicate procedure see Section 4.3. 


arg 
The user-specified arguments that are passed to the predicate procedure. 
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DESCRIPTION 


IF EVENT checks the input event queue for the event that you specify 

in the predicate procedure, and removes the event from the queue 

if the events match. IF EVENT completes only when the predicate 
procedure returns true for an event. You supply a predicate procedure 
that determines if the next event in the event queue matches the event 
you specify in arg. The predicate procedure is called each time an event is 
added to the queue. 


If the predicate procedure returns true, IF EVENT removes the event from 
the queue and, when it returns, copies the event data structure into the 
data structure specified in event_return. 


If IF EVENT does not find a match, it flushes the output buffer and waits 
for an event. The CHECK IF EVENT routine differs in that it returns 
false and does not block if it does not find a match. 


The event data structure is shown in Section 4.1. 
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MASK EVENT 


Removes and copies the next matching event from the queue or blocks until a 
matching event is received. 





VAX FORMAT X$MASK_EVENT 
(display, event_mask, event_return) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
event_mask mask_longword longword read reference 
event_return record x$event write reference 





MITC FORMAT XMaskEvent 
(display, event_mask, event_return) 


argument 

information XMaskEvent (display, event_mask, event_return) 
Display *display; 
long event_mask; 
XEvent *event_return; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_mask 
A bitmask that specifies the events types for which you want to remove an 
event. The event mask is described in Table 4-2. 


e vent_r eturn 

A pointer to the event data structure to which the matching event is 
returned. MASK EVENT copies the matched event’s associated structure 
to this client-supplied structure. The event data structure is shown in 
Section 4.1. 





DESCRIPTION MASK EVENT removes the next event in the queue that matches the 
mask that you specified in event_mask. MASK EVENT copies the event 
into the event structure specified in event_return. Earlier events in the 
queue are not discarded. 


If no matching event is found, MASK EVENT flushes the client’s output 
buffer and then blocks until one is received. 
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The event data structure is shown in Section 4.1. 


Note that MASK EVENT differs from CHECK MASK EVENT in that 
CHECK MASK EVENT returns immediately while MASK EVENT blocks 
until a match is found. CHECK MASK EVENT also returns a Boolean 
value indicating if the event was returned. 
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NEXT EVENT 


Gets the next event and removes it from the queue. NEXT EVENT can flush 
the client’s Xlib output buffer. 





VAX FORMAT X$NEXT_EVENT (display, event_return) 


argument 


information Argument ‘Usage —=—=sData Type == Access. = Mechanism _ 


display identifier uns longword read reference 
event_return record x$event write reference 





MITC FORMAT XNextEvent (display, event_return) 


argument 

information XNextEvent (display, event_return) 
Display *display; 
XEvent *event_return; 





ARGUMENTS _ displa 
The display information originally returned by OPEN DISPLAY. 


event_return 

A pointer to the event structure to which the next event is returned. 
NEXT EVENT copies the next event’s associated structure to this client- 
supplied storage. The event data structure is shown in Section 4.1. 





DESCRIPTION NEXT EVENT copies the next event’s associated structure to the event 
structure specified in event_return and removes the event from the top of 
the event queue. For example, if a Create Notify event is at the top of the 
queue, NEXT EVENT removes it and then copies the create window event 
structure into the event structure specified in event_return. 


If the event queue is empty, NEXT EVENT flushes the client’s output 
buffer and blocks until an event is received. 


NEXT EVENT is similar to PEEK EVENT, except that NEXT EVENT 
removes the event from the queue and PEEK EVENT does not. 


For more information about the event data structure, see Section 4.1. 
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PEEK EVENT 
Looks at and copies an event from the event queue. 
VAX FORMAT X$PEEK_EVENT (display, event_return) 
argument 
information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
event_return record x$event write reference 





MITC FORMAT XPeekEvent (display, event_return) 


argument 

information XPeekEvent (display, event_return) 
Display *display; 
XEvent *event_return; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_return 

A pointer to the event structure to which the next event is returned. 
PEEK EVENT copies the event’s associated structure to this structure. 
The event data structure is shown in Section 4.1. 





DESCRIPTION PEEK EVENT looks at the event at the top of the event queue and copies 
the associated structure to the event structure specified in event_return. 
PEEK EVENT does not remove the event from the event queue. For 
example, if a Create Notify event is at the top of the queue, PEEK EVENT 
copies the create window event structure into event_return. 


If the event queue is empty, PEEK EVENT flushes the client’s output 
buffer then blocks until an event is received. 


PEEK EVENT is similar to NEXT EVENT, except that NEXT EVENT 
removes the event from the queue and PEEK EVENT does not. 


The event data structure is shown in Section 4.1. 
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PEEK IF EVENT 


Checks the event queue for the event that you specify in the predicate 
procedure; does not remove the event from the event queue. 





VAX FORMAT X$PEEK_IF_EVENT 
(display, event_return, predicate, arg) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
event_return record x$event write reference 
predicate procedure proc entry mask _ read reference 
arg longword uns longword read value 





MITC FORMAT XPeeklifEvent 
(display, event_return, predicate, arg) 


argument 
information XPeekI fEvent (display, event_return, predicate, arg) 
Display *display; 
XEvent *event_return; 
Bool (*predicate) (); 
char *arg; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event_retur. n 

A pointer to an event structure to which the matched event is returned. 
PEEK IF EVENT copies the matched event’s associated structure into this 
client-supplied structure. The event data structure is shown in Section 4.1. 


predicate 

A pointer to the user-supplied procedure that determines if the next event 
in the event queue matches the event you specify in the arg argument. 
When true, predicate returns a nonzero value. When false, predicate 
returns zero. Xlib calls the predicate procedure once for each event in the 
queue until it returns a nonzero value. 


For more information on the predicate procedure, see Section 4.3. 


arg 
The user-specified arguments that are passed to the predicate procedure. 
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DESCRIPTION 


PEEK IF EVENT checks the event queue for the event that you specify 
in the arg argument. You supply a predicate procedure that determines 
if the next event in the event queue matches the event you specify in the 
arg argument. This predicate procedure is called each time that an event 
is added to the queue. PEEK IF EVENT returns the event in the event 
argument only when the specified predicate procedure returns true. 


When it returns, PEEK IF EVENT does not remove the event from the 
event queue, but instead copies it to the event structure specified in 
event_return. 


If there is no match, PEEK IF EVENT flushes the Xlib output buffer and 
blocks until a matching event is received. 


The event data structure is shown in Section 4.1. 
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PENDING 


Returns the number of pending input events. 





VAX FORMAT _ count_return=X$PENDING (display) 


argument 


information Argument. Usage ~~dDataType.+—-~«sAccess_~—~=«<Mechanism 


count_return longword longword write value 
display identifier uns longword read reference 





MITC FORMAT count_return=XPending (display) 





argument 

information int XPending (display) 
Display *display; 

RETURNS count_return 


The number of events that have been received by Xlib but are not yet 
removed from the event queue. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 





DESCRIPTION PENDING returns the number of events that have been received by Xlib 
but are not yet removed from the event queue. 


PENDING is identical to EVENTS QUEUED with the mode Queued After 
Flush. 


[ 


0 
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PUT BACK EVENT 


Pushes an event back to the top of the client's event queue. 





VAX FORMAT X$PUT_BACK_EVENT (display, event) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
event record x$event read reference 





MITC FORMAT XPutBackEvent (display, event) 


argument 

information XPutBackEvent (display, event) 
Display *display; 
XEvent *event; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


event 
A pointer to the event structure from which you want to return the event 
to the event queue. The event data structure is shown in Section 4.1. 





DESCRIPTION PUT BACK EVENT copies an event to the top of the event queue. If you 
use a routine such as IF EVENT to remove an event from the event queue, 
you can use PUT BACK EVENT to return the event to the queue. 


There is no limit to the number of times that a client can successively call 
PUT BACK EVENT. 


The event data structure is shown in Section 4.1. 
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SELECT ASYNC EVENT 


Specifies an action routine and argument to be called when an event occurs. 





VAX FORMAT X$SELECT_ASYNC_EVENT 
(display, window_id, event_type, ast_routine, 
ast_userarg) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
event_type longword uns longword read reference 
ast_routine procedure proc entry mask read reference 
ast_userarg longword uns longword read reference 





MIT CFORMAT XSelectAsyncEvent 
(display, window_id, event_type, ast_routine, 
ast_userarg) 


argument 
information XSelectAsyncEvent (display, window_id, event_type, 
ast_routine, ast_userarg) 
Display *display; 
Window window_id; 
unsigned long event_type; 
int (*ast_routine) (); 
unsigned long ast_userarg; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window for which you want to select asynchronous 
events. 


event_type 


The type of event for which you want to select asynchronous events. 


ast_routine 
The particular Asynchronous System Trap (AST) action routine to use 
when notifying the client that the specified event has occurred. 
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SELECT ASYNC EVENT 


ast_userarg 
The user-specified argument to use when notifying the client that the 
specified event has occurred. 





DESCRIPTION 


Before calling SELECT INPUT to specify interest in a particular set of 
events for a window, clients can call SELECT ASYNC EVENT to specify 
an action routine and argument to be called when the specified event 
occurs. 


Xlib uses the client’s ast_routine and ast_userarg information to deliver 
an AST whenever it places the specified event on the event queue. The 
AST acts only as an event notification mechanism; the application uses 
the standard Xlib event routines to actually retrieve and process the event 
from the event queue. 


Clients can call SELECT ASYNC EVENT multiple times to specify 
different routine and argument pairs for different events for a window. 
The last call always takes precedence. If called with ast_routine equal 
to zero, asynchronous notification is disabled, but the current selection for 
the specified event is unaffected. 


Notification ASTs are queued in the same order as events are placed in 
the event queue by Xlib. Therefore, clients can assume that they receive 
notification ASTs in the same order that they find events in the queue. 


SELECT ASYNC EVENT is similar to SELECT ASYNC INPUT except 
that SELECT ASYNC EVENT specifies one event type and SELECT 
ASYNC INPUT specifies an event mask. 
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SELECT ASYNC INPUT 


Specifies an action routine and arguments to be called when some subset of 
events occurs. 





VAX FORMAT X$SELECT_ASYNC_INPUT 
(display, window_id, event_mask, ast_routine, 
ast_userarg) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
event_mask longword uns longword read reference 
ast_routine procedure proc entry mask read reference 
ast_userarg longword uns longword read reference 





MITC FORMAT XSelectAsynclinput 
(display, window_id, event_mask, ast_routine, 
ast_userarg) 


argument 
information XSelectAsyncInput (display, window_id, event_mask, 
ast_routine, ast_userarg) 
Display *display; 
Window window_id; 
unsigned long event_mask; 
int (*ast_routine) (); 
unsigned long ast_userarg; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window for which you want to select asynchronous 
input. 


event_mask 

A bitmask that specifies the event types for which you want to remove 
an event. The mask is an inclusive OR of one or more of the event mask 
elements described in Table 4—2. 
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ast_routine 
The particular Asynchronous System Trap (AST) action routine to use 
when notifying the client that one of the specified events has occurred. 


ast_userarg 
The user-specified parameter to use when notifying the client that one of 
the specified events has occurred. 





DESCRIPTION 


Before calling SELECT INPUT to specify interest in a particular set of 
events for a window, clients can call SELECT ASYNC INPUT to specify 
action routines and arguments to be called when some subset of those 
events occurs. 


Xlib uses the client’s ast_routine and ast_userarg information to deliver 
an AST whenever it places one of the specified events on its event queue. 
The ast_routine and ast_userarg arguments allow the client to specify 
the particular action routine and parameter pair to use when notifying the 
client that one of the specified events has occurred. The AST acts only as 
an event notification mechanism; the application uses the standard Xlib 
event routines to actually retrieve and process the event from the event 
queue. 


Clients can call SELECT ASYNC INPUT multiple times to specify 
different routine and parameter pairs for different sets of events for a 
window. The last call always takes precedence. If called with ast_routine 
equal to zero, asynchronous notification is disabled, but the current 
selection for the specified events is unaffected. 


Notification ASTs are queued in the same order as events are placed in 
the event queue by Xlib. Therefore, clients can assume that they receive 
notification ASTs in the same order that they find events in the queue. 


SELECT ASYNC INPUT is similar to SELECT ASYNC EVENT except 
that SELECT ASYNC EVENT specifies one event type and SELECT 
ASYNC INPUT specifies an event mask. 
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SELECT INPUT 


Selects the events types to send to a window. 





VAX FORMAT X$SELECT_INPUT 
(display, window_id, event_mask) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
event_mask mask_longword longword read reference 





MITC FORMAT XSelectinput 
(display, window_id, event_mask) 


argument 

information XSelectInput (display, window_id, event_mask) 
Display *display; 
Window window_id; 
long event_mask; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window for which you want to select input events. 
Client applications that are interested in an event for a particular window 
pass that window identifier. 


event_mask 

A bitmask that specifies the event types for which you want the window 
to receive notification. This mask is the inclusive OR of one or more event 
mask elements described in Table 4~2. 





DESCRIPTION SELECT INPUT allows you to specify the input events for which a window 
receives notification. If a window is not interested in an event, the event 
propagates until an ancestor of the window expresses interest, or until the 
event is explicitly discarded. Initially, the server does not report any of 
these events. 
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There are two ways to select the events that you want to report to your 
client application. The first way is to set the event mask members of 
the select window attributes data structure when you call CREATE 
WINDOW and CHANGE WINDOW ATTRIBUTES. The second way is 
to use SELECT INPUT. 


Setting the event_mask attribute of a window overrides any previous call 
for the same window, but not for other clients. Multiple clients can select 
events on the same window because their event masks are disjoint. When 
the server generates an event, it reports the event to all interested clients. 
Multiple clients can select the same events on the same window with the 
following restrictions: 


¢ Only one client at a time can select Circulate Request, Configure 
Request, or Map Request events, which are associated with the 
Substructure Redirect mask. 


¢ Only one client at a time can select a Resize Request event, which is 
associated with the Resize Redirect mask. 


¢ Only one client at a time can select a Button Press event, which is 
associated with the Button Press mask. 


The server reports the events to all interested clients. 





X ERRORS 


VAX MIT C Description 


X$C_BAD_WINDOW — BadWindow A value that you specified for a window 
argument does not name a defined window. 
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SEND EVENT 


Sends an event to a window without the window requesting the event. 





VAX FORMAT _ siatus_return = X$SEND_EVENT 
(display, window_id, propagate, event_mask, event) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return cond_value uns longword write value 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
propagate longword longword read reference 
event_mask mask_longword longword read reference 
event record xSevent read reference 





MIT C FORMAT -sstatus_return = XSendEvent 
(display, window_id, propagate, event_mask, event) 


argument 
information Status XSendEvent (display, window_id, propagate, event_mask, 
event) 
Display *display; 
Window window_id; 
Bool propagate; 
long event_mask; 
XEvent *event; 





RETURNS status_return 
Returns false if the conversion to the wire protocol failed. Returns true if 
the conversion to the wire protocol was successful. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 

The identifier of the window to which you want to send the event. This 
window is called the destination window. You can pass the window 
identifier or the constants Pointer Window or Input Focus, which are 
defined as follows: 
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SEND EVENT 
VAX Binding MIT C Binding Description 
XSC_POINTER_ PointerWindow The destination window is the 
WINDOW window that contains the pointer. 
X$C_INPUT_FOCUS InputFocus The destination window is the 


window that has the input focus, 
regardless of whether the window 
contains the pointer. 


propagate 


A Boolean value that determines whether or not to propagate the event. 


If event_mask does not specify any event types, the event is sent to the 
client that created the destination window. If that client no longer exists, 
no event is sent. 


When true, and no client has selected the destination window for any of 
the event types specified in the event mask, the destination is replaced 
with its closest ancestors for which some client has selected a matching 
event type. This condition is true only when intervening windows 
propagate that event type. 


If no such window exists, or if the window is an ancestor of the focus 
window and input focus was originally specified as the destination, then 
the event is not sent to any clients. Otherwise, the event is reported to 
every client that selects any of the types specified in the event mask on 
the final destination. 


When false, the event is sent to every client selecting on destination any of 
the event types specified in event_mask. 


event_mask 

A bitmask that specifies the events types for which you want the window 
to receive notification. This mask is the inclusive OR of one or more of the 
valid event mask elements described in Table 4-2. 


event 
A pointer to the event that is to be sent. 





DESCRIPTION 


SEND EVENT identifies the destination window, determines which clients 
should receive the specified events, and ignores any active grabs. 


The event codes defined by the event_mask argument must be one of the 
core events described in the event structure, or one of the events defined 
by a loaded extension, so that the server can byte swap the contents 

as necessary. The contents of the events are otherwise unaltered and 
unchecked by the server except to force the send event member of the 
forwarded event structure to true and to set the serial number in the 
event. Active grabs are ignored for this request. 


The event data structure is shown in Section 4.1. 
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X ERRORS 


VAX MIT C Description 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Unless you specify a specific range for 
an argument, the full range defined by 
the argumeni’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 


X$C_BAD_WINDOW _— BadWindow A value that you specified for a window 
argument does not name a defined window. 
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SET AFTER FUNCTION 


Specifies the synchronization handler to call before returning from an Xlib 
protocol routine. 





VAX FORMAT X$SET_AFTER_FUNCTION 
(display, func_addr, prev_func_addr_return) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
func_addr procedure proc entry mask read reference 
prev_func_addr_return procedure proc entry mask write reference 





MIT C FORMAT prev_func_return = XSetAfterFunction 
(display, func_addr) 





argument 

information int (*XSetAfterFunction (display, func_addr) ) () 
Display *display; 
int (*func_addr) (); 

RETURNS prev_func_return (MIT C only) 


The previous after function is returned. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


func_addr 

The function to be called after an Xlib function that generates a protocol 
request completes its work. Only a display pointer is passed to the 
function. 


prev_func_addr_return (VAX only) 


The previous synchronization routine is returned. 
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DESCRIPTION — SET AFTER FUNCTION specifies a synchronization routine to call before 
returning from an Xlib routine that generates a protocol request. All 
Xlib routines that generate protocol requests will then call this “after 
function” synchronization routine before returning. You use SET AFTER 
FUNCTION before a call to SYNCHRONIZE to specify a synchronization 
routine. 


The X server does not automatically notify Xlib when the server has 
received and processed an output request. However, when debugging 
your client program, it is sometimes helpful to know that a routine 

has completed successfully, or generated an error, before the next 

output request is sent to the server. To do this, you can use SET 
AFTER FUNCTION to follow each Xlib output request with a call to 

a synchronization routine that generates a return. When your client 
program receives the return, you know that the previous routine completed 
successfully. 


The synchronization routine can be any Xlib or user-written routine 

that generates a return. For example, you can specify a routine that 
generates program statistics. When your client program receives the 
values returned by the statistics routine, you can be sure that the previous 
routine completed successfully or caused an error. 


The synchronization routine is called with one argument, a pointer to the 
display. 
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SET ERROR HANDLER 


Specifies a user-written routine to handle nonfatal errors. 





VAXFORMAT X$SET_ERROR_HANDLER (handler) 


argument 


information Argument Usage -—~—S‘dData Type +=—=—SsAccess.-~=—Ss Mechanism __ 


handler procedure proc entry mask read reference 





MITC FORMAT XSetErrorHandler (handler) 


argument 
H i XSetErrorHandler (handler) 
information int (*handler) (Display*, XErrorEvent*) ; 





ARGUMENTS __ handler 
A user-written routine that handles nonfatal errors. The handler 
argument is the address of the entry mask for the routine. The routine 
returns an integer value. SET ERROR HANDLER passes the following 
arguments to the routine: 


¢ display—Pointer to the display structure associated with the display. 


* error_event—Pointer to the error event. The error must be of type 
X$ERROR_EVENT for the VAX binding and XErrorEvent for the 
MIT C binding. 





DESCRIPTION SET ERROR HANDLER specifies the user-written error handler to be 
called whenever an error event is received. These errors are assumed to 
be nonfatal, and it is acceptable for the error handler to return control 
to the client program. However, the error handler should not call any 
routines (directly or indirectly) that generate protocol requests or look for 
input events. 
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SET ERROR HANDLER 
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The error handler is not called for the following conditions: 


¢ On Bad Name errors from OPEN FONT, LOOKUP COLOR, and 
ALLOC NAMED COLOR protocol requests 


¢ On Bad Font errors from a QUERY FONT protocol request 


¢ On Bad Alloc or Bad Access errors from syncronous protocol requests 


These errors are reflected back to the program through the routine’s return 
value. Errors are listed for a routine only if the error results in a call to 
the error handler. 


The error event structure defines the format of errors reported to the 
default or user-supplied error handlers. 


The attributes of the error event structure are as follows: 


Member Description 
display The display from which the event was read. 
serial The total number of protocol requests, starting from one, sent across 


the transport since the connection was opened. This member 
reflects the number of the request immediately before the failing call 


was made. 
error_code The identifying error code of the failing call. 
request_code —_ The operation code for the protocol request that failed. 
minor_code The minor operation code for the protocol request that failed. 
resource_id The resource identifier for which the error occured. 


The error event data structure is shown in Section 4.6. 
See also the SET IO ERROR HANDLER routine. 
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SET lO ERROR HANDLER 


Specifies a user-written routine to handle fatal I/O errors. 





VAXFORMAT X$SET_IO ERROR_HANDLER (handler) 


argument 


information Argument ‘Usage —=iDataType_+=—=—=sAccess.~=—S—s Mechanism _ 


handler procedure proc entry mask read reference 





MITC FORMAT XSetlOErrorHandler (handler) 


argument 
A H XSetlOErrorHandler (handler) 
information int (*handler) (Display*); 





ARGUMENTS handler 


A user-written routine that handles fatal errors. The handler argument is 
the address of the entry mask for the routine. SET IO ERROR HANDLER 
passes a pointer to the display structure to the routine. 





DESCRIPTION SET IO ERROR HANDLER specifies a user-written error handler to be 
called by Xlib if any type of system-call error, such as losing the connection 
to the server, occurs. This is assumed to be a fatal condition; the error 
handler should not return. If the IO error handler does return, the client 
process exits. 


Also see the SET ERROR HANDLER routine. 
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Flushes the client’s Xlib output buffer and waits for all requests to be received 
and processed by the server. 





VAX FORMAT X$SYNC_ (display, discard) 


argument 


information Argument Usage -—iDataType+=—=—sAccess.~=—s Mechanism _ 


display identifier uns longword read reference 
discard longword longword read reference 





MITC FORMAT XSync_ (display, discard) 


argument 

information XSync (display, discard) 
Display *display; 
Bool discard; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


discard 

If true, SYNC discards all events on the client event queue, including 
those events that were on the queue before SYNC was called. If discard is 
false, SYNC does not discard the events on the queue. 





DESCRIPTION SYNC flushes the client’s Xlib output buffer and then waits until all 
requests have been received and processed by the server. New events 
are placed on the Xlib event queue by the server. Any errors that are 
generated must be handled by the error handler; the client’s error handling 
routine is called once for each error received. 


Client applications seldom need to call SYNC. 
See also the SYNCHRONIZE routine. 
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SYNCHRONIZE 

Enables or disables synchronization for a display. 

VAX FORMAT _ state_return = X$SYNCHRONIZE 

(display, onoff, after_function_return) 

argument 

information Argument Usage Data Type Access Mechanism 
state_return longword longword write value 
display identifier uns longword read reference 
onoff longword longword read reference 
after_function_return procedure proc entry mask write reference 





MIT C FORMAT = after_return = XSynchronize 





(display, onoff) 
argument 
information int (*XSynchronize(display, onoff)) () 
Display *display; 
Bool onoff; 
RETURNS state_return (VAX only) 


Specifies whether the routine completed successfully. The argument 
returns true if an after function was present and returns false if no after 
function was present. 


after_return (MIT C only) 

The address of the after function. The after function specifies a 
synchronization routine to call before returning from an Xlib routine that 
generates a protocol request. See the SET AFTER FUNCTION routine for 
more information. 





ARGUMENTS _~ display 
The display information originally returned by OPEN DISPLAY. 


onoff 
A Boolean value that enables or disables synchronization. Possible values 
are zero (disable) or nonzero (enable). 


after_function_return (VAX only) 


The previous after function is returned. 
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DESCRIPTION SYNCHRONIZE enables or disables synchronization and returns the after 
function. The X server does not automatically notify Xlib when the server 
has received and processed an output request. However, when debugging 
your client program, it is sometimes helpful to know that a routine has 
completed successfully, or generated an error, before the next output 
request is sent to the server. 


SYNCHRONIZE flushes the client’s Xlib output buffer after each Xlib 
routine then calls a synchronization routine that generates a return. 
When your client program receives the return, you know that the previous 
routine completed. If an output request generates an error, the server 
reports the error back to the client at the time it occurs. 


SYNCHRONIZE uses the window and session manager routine GET 
INPUT FOCUS as the default synchronization routine. You can use SET 
AFTER FUNCTION to specify another synchronization routine. 


Note that when you enable synchronization, all output for the display is 
synchronized. Graphics output may occur dramatically (30 or more times) 
slower when synchronization is enabled because of the increased overhead 
incurred by sending each output request individually and waiting for a 
return or error condition. 


SYNCHRONIZE is similar to SYNC, except that SYNCHRONIZE flushes 
the output buffer after each Xlib routine and waits for the after function 
return value to be returned; SYNC flushes the output buffer only once and 
may also clear the event queue. 
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WINDOW EVENT 


Removes the next matching event from the queue for the specifed window. 





VAX FORMAT X$WINDOW_EVENT 
(display, window_id, event_mask, event_return) 


argument 


information Agiien: ings. Daye Aes 


display identifier uns longword read reference 
window_id identifier uns longword read reference 
event_mask mask_longword uns longword read reference 
event_return record x$event write reference 





MITC FORMAT XWindowEvent 
(display, window_id, event_mask, event_return) 


argument 
information XWindowEvent (display, window_id, event_mask, event_return) 
Display *display; 
Window window_id; 
long event_mask; 
XEvent *event_return; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window for which you want to remove the next 
matching event. 


event_mask 

A bitmask that specifies the event types for which you want to remove 
an event. This mask is the inclusive OR of one or more of the valid event 
mask elements described in Table 4-2. 


event_return 

A pointer to the event structure to which the matching event is returned. 
WINDOW EVENT copies ~he matched event’s associated structure into 
this client-supplied structure. The event data structure is shown in 
Section 4.1. 


Event Routines 
WINDOW EVENT 





DESCRIPTION WINDOW EVENT searches the event queue for an event that matches 
both the specified window and event mask. If it finds a match, WINDOW 
EVENT removes the event from the queue and copies it into an event 
structure supplied in the event_return argument. Other events in the 
queue are not discarded. If no such event has been queued, WINDOW 
EVENT flushes the output buffer and blocks until one is received. 


Note that WINDOW EVENT differs from CHECK WINDOW EVENT in 
that CHECK WINDOW EVENT returns immediately while WINDOW 
EVENT blocks until a match is found. 


The event data structure is shown in Section 4.1. 
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5 Graphics Context Routines 


Graphics contexts are data structures that specify several graphics 
attributes. For example, the graphics routines use the graphics context 
attributes to define how various operations are performed. For example, 
when a line is drawn, the graphics routine DRAW LINE uses a GC values 
data structure to define how wide the line is, how to draw the end points 
of the line, and which pattern to use to fill the line. For more information 
about graphics routines, see Chapter 6. 


The graphics context routines enable you to perform the following 
operations: 


¢ Create GC values data structures 
¢ Manipulate the data structures 


¢ Change members within the data structure 


For concepts related to graphics context routines and information on 
how to use graphics context routines, see the VMS DECwindows Xlib 
Programming Volume. 


The routines described in this chapter are listed in Table 5-1. 


Table 5-1 Graphics Context Routines 


Routine Name Description 
CHANGE GC Change any attribute by changing the values 


in the graphics context data structure. 


COPY GC Copies the graphics context values from one 
graphics context data structure to another 
graphics context data structure. 


CREATE GC Creates a new graphics context for a specific 
window. Unless specified, the members of the 
graphics context are the default values. 


FREE GC Frees the storage associated with the graphics 
context and its identifier. 

GCONTEXT FROM GC Obtains the graphics context resource 
identifier for a specified graphics context. 

QUERY BEST SIZE Obtains the optimal size for improved server 


performance for the cursor, the tile pattern, or 
the stipple pattern. 


QUERY BEST STIPPLE Obtains the optimal size for improved server 
performance for a stipple pattern. 


(continued on next page) 
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Graphics Context Routines 


Table 5-1 (Cont.) Graphics Context Routines 


Routine Name 


QUERY BEST TILE 


SET ARC MODE 
SET BACKGROUND 


SET CLIP MASK 


SET CLIP ORIGIN 


SET CLIP RECTANGLES 


SET DASHES 


SET FILL RULE 


SET FILL STYLE 


SET FONT 


SET FOREGROUND 


SET FUNCTION 
SET GRAPHICS EXPOSURES 
SET LINE ATTRIBUTES 


SET PLANE MASK 


SET STATE 


SET STIPPLE 


SET SUBWINDOW MODE 


SET TILE 


SET TS ORIGIN 


The GC Values Data Structure 


Description 


Obtains the optimal size for improved server 
performance for a tile pattern. 


Sets the arc mode to the value specified. 


Sets the background color index to the value 
specified. 


Changes the pixmap identifier of the clip mask 
for the specified graphics context. 


Changes the clip origin members in the 
specified graphics context. 


Changes the clip origin members in the 
specified graphics context and specifies 
rectangular clip areas. 


Changes the values for the dash offset and 
the dash list. 


Sets the fill rule member in the graphics 
context to the value specified. 


Sets the fill style member in the graphics 
context to the value specified. 


Changes the identifier of the font in the 
specified graphics context. 


Sets the foreground color index to the value 
specified. 


Sets the function value to the value specified. 
Changes the graphics exposure. 


Changes the line drawing members in the 
graphics context. 
Sets the plane mask to the value specified. 


Changes values for the foreground, 
background, plane mask, and function 
members of the graphics context. 


Changes the pixmap identifier of the stipple 
pattern in the specified graphics context. 


Changes the value for the subwindow mode 
member in the graphics context. 


Changes the pixmap identifier of the tile 
pattern in the specified graphics context. 


Changes the x- and y-coordinates of the tile or 
stipple origin in the graphics context. 


The GC values data structure stores all the values for each of 23 graphics 


context members. 


Graphics Context Routines 
5.1 The GC Values Data Structure 


The data structure for the VAX binding is shown in Figure 5-1, and 
information about members in the data structure is described in 
Table 5-2. 


Figure 5-1 GC Values Data Structure (VAX Binding) 
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Graphics Context Routines 
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Table 5-2 Members of the GC Values Data Structure (VAX Binding) 


Member Name 


X$L_GCVL_FUNCTION 


X$L_GCVL_PLANE_MASK 


X$L_GCVL_FOREGROUND 
X$L_GCVL_BACKGROUND 


Contents 


Defines how the server computes pixel values when the client updates 
a section of the screen. The following lists available functions: 





Constant Name Description 
X$C_GX_CLEAR 0 

x$C_GX_AND src AND dst 
X$C_GX_AND_REVERSE src AND NOT dst 
X$C_GX_COPY src 
X$C_GX_AND_INVERTED (NOT src} AND dst 
X$C_GX_NOOP dst 

X$C_GX_XOR src XOR dst 
X$C_GX_OR src OR dst 
X$C_GX_NOR (NOT src) AND NOT dst 
X$C_GX_EQUIV (NOT src) XOR dst 
X$C_GX_INVERT NOT dst 
X$C_GX_OR_REVERSE src OR NOT dst 
X$C_GX_COPY_INVERTED NOT src 


X$C_GX_OR_INVERTED 


(NOT src) OR dst 


X$C_GX_NAND (NOT src) OR NOT dst 
X$C_GX_SET 1 


The screen the client is updating is the destination (dst). The graphics 
context the client uses to update the screen is the source (src). 
X$L_GCVL_FUNCTION specifies how the server computes new 
destination bits from the source (src) and the old bits of the destination 
(dst). 

The most common logical function is the default specified by the 
constant x$c_gx_copy, which uses only relevant values in the specified 
GC values structure to update the screen. 


Specifies the planes on which the server performs the bitwise 
computation of pixels, defined by X$L_GCVL_FUNCTION. 


Because a monochrome display has only one plane, the plane mask 
value is given in the least signficant bit of the longword. As planes are 
added to the display hardware, they are defined in the more signficant 
bits of the mask. The display routine ALL PLANES specifies that all 
planes of the display are referred to simultaneously. 


The server does not perform range checking on the plane mask. It 
truncates values to the appropriate number of bits. 


Specifies an index to a color map for foreground color. 
Specifies an index to a color map for background color. 
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Table 5-2 (Cont.) Members of the GC Values Data Structure (VAX Binding) 


Member Name 


X$L_GCVL_LINE_WIDTH 


Contents 


Defines the width of a line in pixels. 


The server draws a line with a width of two or more pixels centered 
on the path described in the graphics request and contained within a 
bounding box. Unless otherwise specified by the join or cap style, the 
bounding box of a line with endpoints [ 21, y1], [ 22, y2] and width w 
is a rectangle with vertices at the following real coordinates: 


[xl-w*sn/2, yl+w*cs/2], [xl+w*sn/2, yl-w*cs/2] 
[x2-w*sn/2, y2twxcs/2], [x2+w*sn/2, y2-w*cs/2] 


In this example, sn is the sine of the angle of the line. The symbol cs 
is the cosine of the angle of the line. A pixel is part of the line and is 
drawn if the center of the pixel is fully inside the bounding box. If the 
center of the pixel is exactly on the bounding box, the pixel is part of 
the line if and only if the interior is immediately to its right (x increasing 
direction). Pixels with centers on a horizontal edge are a special case 
and are part of the line if and only if the interior is immediately below 
the bounding box (y increasing direction). 


Lines with zero line width are one pixel wide. The server draws them 
using an unspecified, device-dependent algorithm that imposes the 
following two constraints: 


« — If the server draws the line unclipped from [ <1, y1] to [ «2, y2], 
and if the server draws a second line from [ 21+ dz, y1 + dy] to [ 
22+ dz, y2+ dy], then point [ 2, y] is touched by drawing the first 
line if and only if the point [ + dz, y + dy] is touched by drawing 
the second line. 

* The effective set of points that compose a line cannot be affected 
by clipping. That is, a point is touched in a clipped line if and only 
if the point lies inside the clipping region and if the point would be 
touched by the line when drawn unclipped. 


A line more than one pixel wide drawn from [ 21, y1] to [ 22, y2] 
always draws the same pixels as a line of the same width drawn from 
[ 22, y2] to [ 21, y1], excluding cap and join styles. 


In general, drawing a line whose line width is zero is faster than 
drawing a line whose line width is one or more. However, because 
the drawing algorithms for thin lines is different than those for wide 
lines, thin lines may not look as good when mixed with wide lines. 
lf clients want precise and uniform results across all displays, they 
should always use a line width of one or more. Note, however, that 
specifying a line width of greater than zero decreases performance 
substantially. 
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Table 5-2 (Cont.) Members of the GC Values Data Structure (VAX Binding) 


Member Name Contents 
X$L_GCVL_LINE_STYLE Defines which sections of the line the server draws. The following lists 


available line styles and the constants that specify them. Figure 5-2 


illustrates the styles. 


Constant Name 


x$c_line_solid 
x$c_line_double_dash 


x$c_line_off_on_dash 


Description 


The full path of the line is drawn. 


The full path of the line is drawn, but the 
even dashes are filled differently from 
the odd dashes, with cap butt style used 
where even and odd dashes meet. 


Only the even dashes are drawn. The 
X$L_CAP_STYLE member applies to all 
internal ends of dashes. Specifying the 
constant, x$c_cap_not_last, is equivalent 
to specifying x$c_cap_butt. 


X$L_GCVL_CAP_STYLE Defines how the server draws the endpoints of a path. The following 
lists available cap styles and the constants that specify them. 
Figure 5-3 illustrates the available cap styles. 


Constant Name 


x$c_cap_not_last 


x$c_cap_butt 


x$c_cap_round 


x$c_cap_projecting 
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Description 


Equivalent to specifying x$c_cap_butt, 
except that the final endpoint is not 
drawn if the line width is zero or one 


Square at the endpoint (perpendicular to 
the slope of the line) with no projection 
beyond the endpoint 


A circular arc with the diameter equal to 
the line width, centered on the endpoint 
(equivalent to specifying x$c_cap_buit 
for a line width of zero or one) 


Square at the end, but the path 
continues beyond the endpoint for a 
distance equal to half the width of the 
line (equivalent to specifying 
x$c_cap_butt for a line width of zero or 
one) 
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Table 5-2 (Cont.) Members of the GC Values Data Structure (VAX Binding) 


Member Name 


X$L_GCVL_JOIN_STYLE 


Contents 


If a line has coincident endpoints ( #1 = 22, yl = y2), the cap style is 
applied to both endpoints with the following results: 


Line 

Constant Name Width Description 

x$c_cap_not_last Thin Device dependent, but the 
desired effect is that nothing is 
drawn 

x$c_cap_butt Thin Device dependent, but the 
desired effect is that a single 
pixel is drawn 

x$c_cap_buitt Wide Nothing is drawn 

x$c_cap_round Thin Device dependent, but the 


desired effect is that a single 
pixel is drawn 


x$c_cap_round Wide The closed path is a circle, 
centered at the endpoint, with the 
diameter equal to the line width 


x$c_cap_projecting Thin Device dependent, but the 
desired effect is that a single 
pixel is drawn 


x$c_cap_projecting Wide The closed path is a square, 
aligned with the coordinate axes, 
centered at the endpoint with 
sides equal to the line width 


Defines how the server draws corners for wide lines. Available join 
styles and the constants that specify them are as follows: 


Constant Name Description 

x$c_join_mitre The outer edges of the two lines extend to 
meet at an angle. 

x$c_join_round A circular arc with diameter equal to the line 
width, centered at the join point. 

x$c_join_bevel Cap buit endpoint style, with the triangular 
“notch” filled. 





For a line with coincident endpoints ( 21 = 22, yl = y2), when the 
join style is applied at one or both endpoints, the effect is as if the 
line were removed from the overall path. However, if the total path 
consists of (or is reduced to) a single point joined with itself, the effect 
is the same as if the X$L_GCVL_CAP_STYLE were applied to both 
endpoints. Figure 5~4 illustrates the styles. 
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Table 5-2 (Cont.) Members of the GC Values Data Structure (VAX Binding) 


Member Name 


X$L_GCVL_FILL_STYLE 


X$L_GCVL_FILL_RULE 


Contents 


Specifies the contents of the source for line, text, and fill operations. 
The following lists available fill styles for text and fill requests (DRAW 
TEXT, DRAW TEXT 16, FILL RECTANGLE, FILL POLYGON, FILL 
ARC). It also lists available styles applicable to solid lines and even 
dashes resulting from line requests (LINE, SEGMENTS, RECTANGLE, 
ARC): 


Constant Name Description 

x$c_fill_solid Foreground 

x$c_fill_tiled Tile 

x$c_fill_opaque_stippled A tile with the same width and height 


as stipple, but with background 
everywhere stipple has a zero and 
with foreground everywhere stipple 
has a one 


x$c_fill_stippled Foreground masked by stipple 


The following lists available styles applicable to odd dashes resulting 
from line requests: 


Constant Name Description 

x$c_fill_solid Background 

x$c_fill_tiled Tile 

x$c_fill_opaque_stippled A tile with the same width and height 


as stipple, but with background 
everywhere stipple has a zero and 
with foreground everywhere stipple 


has a one 
x$c_fill_stippled Background masked by stipple 


Defines what pixels the server draws along a path when a polygon is 
filled. The two available choices are x$c_even_odd_rule and 
x$c_winding_rule. The x$c_even_odd_rule constant defines a point to 
be inside a polygon if an infinite ray with the point as origin crosses 
the path an odd number of times. If the point meets these conditions, 
the server draws a corresponding pixel. 
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Table 5-2 (Cont.) Members of the GC Values Data Structure (VAX Binding) 


Member Name 


X$L_GCVL_ARC_MODE 


X$L_GCVL_TILE 


X$L_GCVL_STIPPLE 


X$L_GCVL_TS_X_ORIGIN 


X$L_GCVL_TS_Y_ORIGIN 


X$L_GCVL_FONT 


Contents 


The x$c_winding_rule constant defines a point to be inside the 
polygon if an infinite ray with the pixel as origin crosses an unequal 
number of clockwise and counterclockwise directed path segments. A 
clockwise directed path segment is one that crosses the ray from left 
to right as observed from the pixel. A counterclockwise segment is 
one that crosses the ray from right to left as observed from that point. 
When a directed line segment coincides with a ray, choose a different 
ray that is not coincident with a segment. If the point meets these 
conditions, the server draws a corresponding pixel. 


For both even odd rule and winding rule, a point is infinitely small, and 
the path is an infinitely thin line. A pixel is inside the polygon if the 
center point of the pixel is inside, and the center point is not on the 
boundary. If the center point is on the boundary, the pixel is inside if 
and only if the polygon interior is immediately to its right (x increasi 
direction). Pixels with centers along a horizontal edge are a special 
case and are inside if and only if the polygon interior is immediately 
below (y increasing direction). Figure 5-5 illustrates fill rules. 


Controls how the server fills an arc. The available choices are 
specified by the constants x$c_arc_pie_slice and x$c_arc_chord. 
Figure 5-6 illustrates the two modes. 


Specifies the pixmap the server uses for tiling operations. The pixmap 
must have the same root and depth as the graphics context or an 
error occurs. Clients can use any size pixmap for tiling, although 
some sizes are faster than others. 


Storing a pixmap in a graphics context might or might not result in a 
copy being made. If the pixmap is later used as the destination for a 
graphics request, the change might or might not be reflected in the 
graphics context. If the pixmap is used simultaneously in a graphics 
request both as a destination and as a tile, the results are not defined. 


Specifies the pixmap the server uses for stipple operations. The 
pixmap must have the same root as the graphics context and a depth 
of one, or an error occurs. For stipple operations where the fill style 
is specified as x$c_fill_stippled but not x$c_fill_opaque_stipple, the 
stipple pattern is tiled in a single plane and acts as an additional clip 
mask. Perform a bitwise AND operation with the clip mask. Clients 
can use any size pixmap for stipple operations, although some sizes 
are faster than others. 


Defines the origin for tiling and stipple operations. Origins are relative 
to the origin of whatever window or pixmap is specified in the graphics 
request. 


Defines the origin for tiling and stipple operations. Origins are relative 
to the origin of whatever window or pixmap is specified in the graphics 
request. 


Specifies the font that the server uses for text operations. 





(continued on next page) 
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Table 5-2 (Cont.) Members of the GC Values Data Structure (VAX Binding) 


Member Name 


X$L_GCVL_SUBWINDOW_MODE 


X$L_GCVL_GRAPHIC_EXPOSURES 
X$L_GCVL_CLIP_X_ORIGIN 
X$L_GCVL_CLIP_Y_ORIGIN 


X$L_GCVL_CLIP_MASK 


X$L_GCVL_DASH_OFFSET 


X$T_GCVL_DASHES 


Contents 


Specifies whether inferior windows clip superior windows. The 
constant x$c_clip_by_children specifies that all viewable input-output 
children clip both source and destination windows. The constant 
x$c_include_inferiors specifies that inferiors clip neither source nor 
destination windows. This results in drawing through subwindow 
boundaries. The semantics of using the constant on a window with a 
depth of one and with mapped inferiors of differing depth is undefined 
by the core protocol. 


Specifies whether the server informs the client when the contents of a 
window region are lost. 


Defines the x-coordinate of the clip origin. The clip origin specifies the 
point within the clip region that is aligned with the drawable origin. 


Defines the y-coordinate of the clip origin. The clip origin specifies the 
point within the clip region that is aligned with the drawable origin. 


Identifies the pixmap the server uses to restrict write operations to 
the destination that is drawable. The pixmap must have a depth of 
one and have the same root as the graphics context. The clip mask 
clips only the destination that is drawable, not the source drawable. 
Where a value of one appears in the mask, the corresponding pixel 
in the destination drawable is drawn; where a value of zero occurs, 
no pixel is drawn. Any pixel within the destination drawable that is not 
represented within the clip mask pixmap is not drawn. When a client 
specifies the value of clip mask as x$c_none, the server draws all 
pixels. 


Specifies the pixel within the dash length sequence, defined by 
X$T_GCVL_DASHES, to start drawing a dashed line. For example, a 
dash offset of zero starts a dashed line as the beginning of the dash 
line sequence. A dash offset of five starts the line at the fifth pixel of 
the line sequence. 


Specifies the length, in number of pixels, of each dash. The value of 
this member must be nonzero or an error occurs. 





Figure 5-2 Line Styles 


Solid 


Double Dash 


On Off Dash 
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Figure 5-3 Cap Styles 





Butt Butt 
gee 
Round Not Last 
Cc 
Cap Styles for Thin Lines 
Projecting (Line Widths of 0 and 1) 
Cap Styles for Wide Lines 
(Line Widths Greater Than 1) ZK-0021A-GE 


The default values for the GC values data structure are listed in Table 5—3. 
These values are used in the default graphics context. 
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Figure 5-4 Join Styles 
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Figure 5-5 Fill Rules 
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Figure 5-6 Arc Fill Options 
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Table 5-3 Default Values for the GC Values Data Structure 


Member 


X$L_GCVL_FUNCTION 
X$L_GCVL_PLANE_MASK 
X$L_GCVL_FOREGROUND 
X$L_GCVL_BACKGROUND 
X$L_GCVL_LINE_WIDTH 
X$L_GCVL_LINE_STYLE 
X$L_GCVL_CAP_STYLE 
X$L_GCVL_JOIN_STYLE 
X$L_GCVL_FILL_STYLE 
X$L_GCVL_FILL_RULE 
X$L_GCVL_ARC_MODE 
X$L_GCVL_TILE 


X$L_GCVL_STIPPLE 
X$L_GCVL_TS_X_ORIGIN 
X$L_GCVL_TS_Y_ORIGIN 
X$L_GCVL_FONT 
X$L_GCVL_SUBWINDOW_MODE 


X$L_GCVL_GRAPHICS_ 
EXPOSURES 


X$L_GCVL_CLIP_X_ORIGIN 
X$L_GCVL_CLIP_Y_ORIGIN 
X$L_GCVL_CLIP_MASK 
X$L_GCVL_DASH_OFFSET 
X$L_GCVL_DASH_LIST 


Default Value 


X$CGX_COPY 
All ones 

0 

1 

0 
x$c_line_solid 
x$c_cap_butt 
x$c_join_mitre 
x$c_fill_solid 
x$c_even_odd 
x$c_arc_pie_slice 


Pixmap of unspecified size filled with 
foreground pixel 


Pixmap of unspecified size filled with ones 
0 

0 

Can vary 

x$C_clip_by_children 

True 


0 

0 

None 

0 

4 (the list [4,4]) 


The data structure for the MIT C binding is shown in Figure 5-7, 
and information about members in the data structure is described in 


Table 5—4. 
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Figure 5-7 GC Values Data Structure (MIT C Binding) 


typedef struct { 
int function; 
unsigned long plane_mask; 
unsigned long foreground; 
unsigned long background; 
int line width; 
int line style; 
int cap_style; 
int join_style; 
int fill_style; 
int fill_rule; 
int arc_mode; 
Pixmap tile; 
Pixmap stipple; 
int ts_x_origin; 
int ts_y origin; 
Font font; 
int subwindow_mode; 
Bool graphics_exposures; 
int clip_x_origin; 
int clip_y_ origin; 
Pixmap clip_mask; 
int dash_offset; 
char dashes; 
} XGCValues; 


Table 5-4 Members of the GC Values Data Structure (MIT C Binding) 





Member Name 


function 


Contents 


Defines how the server computes pixel values when the client updates a section of 
the screen. The following lists available functions: 


Constant Name Description 
GXclear 0 

GXand src AND dst 
GXandReverse src AND NOT dst 
GXcopy src 

GXandlInverted (NOT src) AND dst 
GXnoop dst 

GXxor sre XOR dst 

GXor src OR dst 

GXnor (NOT src) AND NOT dst 
GXequiv (NOT src) XOR dst 
GXinvert NOT dst 


(continued on next page) 
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Table 5-4 (Cont.) Members of the GC Values Data Structure (MIT C Binding) 





Member Name 


plane_mask 


foreground 
background 
line_width 
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Contents 

Constant Name Description 
GXorReverse src OR NOT dst 
GXcopylnverted NOT src 

GXorlInverted (NOT src) OR dst 
GXnand (NOT src) OR NOT dst 
GXset 1 


The screen the client is updating is the destination (dst). The graphics context the 
client uses to update the screen is the source (src). The function member specifies 
how the server computes new destination bits from the source (src) and the old bits 
of the destination (dst). 


The most common logical function is the default specified by the constant GXcopy, 
which only uses relevant values in the specified GC VALUES structure to update the 
screen. 


Specifies the planes on which the server performs the bitwise computation of pixels, 
defined by function. 


Because a monochrome display has only one plane, the plane mask value is given in 
the least significant bit of the longword. As planes are added to the display hardware, 
they are defined in the more significant bits of the mask. The display routine ALL 
PLANES specifies that all planes of the display are referred to simultaneously. 


The server does not perform range checking on the plane mask. It truncates values 
to the appropriate number of bits. 


Specifies an index to a color map for foreground color. 
Specifies an index to a color map for background color. 
Defines the width of a line in pixels. 


The server draws a line with a width of two or more pixels centered on the path 
described in the graphics request and contained within a bounding box. Unless 
otherwise specified by the join or cap style, the bounding box of a line with endpoints 
[ #1, y1], [ #2, y2] and width w is a rectangle with vertices at the following real 
coordinates: 


[xl-w*sn/2, ylt+w*cs/2], [xl+w*sn/2, yl-w*cs/2] 
[x2-w*sn/2, y2tw*cs/2], [x2+w*sn/2, y2-w*cs/2] 


In this example, sn is the sine of the angle of the line. The symbol cs is the cosine of 
the angle of the line. A pixel is part of the line and is drawn if the center of the pixel 
is fully inside the bounding box. If the center of the pixel is exactly on the bounding 
box, the pixel is part of the line if and only if the interior is immediately to its right 

(x increasing direction). Pixels with centers on a horizontal edge are a special case 
and are part of the line if and only if the interior is immediately below the bounding 
box (y increasing direction). 
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Table 5-4 (Cont.) Members of the GC Values Data Structure (MIT C Binding) 


Member Name 


Contents 





line_style 


Lines with zero line width are one pixel wide. The server draws them using an 
unspecified, device-dependent algorithm that imposes the following two constraints: 


+ — If the server draws the line unclipped from [ 21, y1] to [ 22, y2], and if the server 
draws a second line from [ 21+ dz, y1 + dy] to [ 22 + dz, y2+ dy], then point 
{ z, y] is touched by drawing the first line if and only if the point [2+ dz, y + dy] 
is touched by drawing the second line. 

* The effective set of points that compose a line cannot be affected by clipping. 
That is, a point is touched in a clipped line if and only if the point lies inside 
the clipping region and if the point would be touched by the line when drawn 
unclipped. 


A line more than one pixel wide drawn from [ #1, y1] to [ 22, y2] always draws the 
same pixels as a line of the same width drawn from [ 22, y2] to [ #1, y1], excluding 
cap and join styles. 


in general, drawing a line whose line width is zero is faster than drawing a line whose 
line width is one or more. However, because the drawing algorithms for thin lines is 
different than those for wide lines, thin lines may not look as good when mixed with 
wide lines. If clients want precise and uniform results across all displays, they should 
always use a line width of one or more. Note, however, that specifying a line width of 
greater than zero decreases performance substantially. 


Defines which sections of the line the server draws. The following lists available line 
styles and the constants that specify them: 


Constant 
Name Description 
LineSolid The full path of the line is drawn 


LineDoubleDash _ The full path of the line is drawn, but the even dashes are filled 
differently than the odd dashes, with cap butt style used where 
even and odd dashes meet 


LineOffOnDash — Only the even dashes are drawn. The cap_style member applies 
to all internal ends of dashes. Specifying the constant CapNotLast 
is equivalent to specifying CapBuitt. 


Figure 5~2 illustrates the styles. 


{continued on next page) 
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Table 5—4 (Cont.) Members of the GC Values Data Structure (MIT C Binding) 


Member Name Contents 


cap_style Defines how the server draws the endpoints of a path. The following lists available 

cap styles and the constants that specify them: 

Constant 

Name Description 

CapNotLast Equivalent to CapButt, except that the final endpoint is not drawn if 
the line width is zero or one 

CapButt Square at the endpoint (perpendicular to the slope of the line) with 
no projection beyond the endpoint 

CapRound A circular arc with the diameter equal to the line width, centered on 


the endpoint (equivalent to the value specified by CapButt for a line 
width of zero or one) 


CapProjecting Square at the end, but the path continues beyond the endpoint for 
a distance equal to half the width of the line (equivalent to the value 
specified by the constant CapButt for a line width of zero or one) 


Figure 5—3 illustrates the butt, round, and projecting cap styles. 


\f a line has coincident endpoints ( 21 = 22, y1 = y2), the cap style is applied to both 
endpoints with the following results: 


Constant Line 

Name Width Description 

CapNotLast Thin Device dependent, but the desired effect is that nothing 
is drawn 

CapButt Thin Device dependent, but the desired effect is that a single 
pixel is drawn 

CapButt Wide Nothing is drawn 

CapRound Thin Device dependent, but the desired effect is that a single 
pixel is drawn 

CapRound Wide The closed path is a circle, centered at the endpoint, with 
the diameter equal to the line width 

CapProjecting = Thin Device dependent, but the desired effect is that a single 


pixel is drawn 


CapProjecting Wide The closed path is a square, aligned with the coordinate 
axes, centered at the endpoint with sides equal to the 
line width 





(continued on next page) 


5-18 


Graphics Context Routines 
5.1 The GC Values Data Structure 


Table 5—4 (Cont.) Members of the GC Values Data Structure (MIT C Binding) 





Member Name 


Contents 





join_style 


fill_style 


Defines how the server draws corners for wide lines. Available join styles and the 
constants that specify them are as follows: 








Constant 

Name Description 

JoinMitre The outer edges of the two lines extend to meet at an angle. 

JoinRound A circular arc with diameter equal to the line width, centered at the 
join point. 

JoinBevel Cap butt endpoint style, with the triangular “notch” filled. 





Figure 5—4 illustrates the styles. 


For a line with coincident endpoints ( 21 = #2, yl = y2), when the join style is applied 
at one or both endpoints, the effect is as if the line were removed from the overall 
path. However, if the total path consists of (or is reduced to) a single point joined 
with itself, the effect is the same as if the cap style were applied to both endpoints. 


Specifies the contents of the source for line, text, and fill operations. The following 
lists available fill styles for text and fill requests (DRAW TEXT, DRAW TEXT 16, FILL 
RECTANGLE, FILL POLYGON, FILL ARC). It also lists available styles applicable 

to solid lines and even dashes resulting from line requests (LINE, SEGMENTS, 
RECTANGLE, ARC): 


Constant Name Description 
FillSolid Foreground 
FillTiled Tile 


FillOpaqueStippled A tile with the same width and height as stipple, but 
with background everywhere stipple has a zero and with 
foreground everywhere stipple has a one 


FillStippled Foreground masked by stipple 





The following lists available styles applicable to odd dashes resulting from line 
requests: 


Constant Name Description 
FillSolid Background 
FillTiled Tile 


FillOpaqueStippled A tile with the same width and height as stipple, but 
with background everywhere stipple has a zero and with 
foreground everywhere stipple has a one 


FillStippled Background masked by stipple 





(continued on next page) 
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Table 5-4 (Cont.) Members of the GC Values Data Structure (MIT C Binding) 


Member Name 


fill_rule 


arc_mode 


tile 


stipple 


ts_x_origin 
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Contents 


Defines what pixels the server draws along a path when a polygon is filled. The two 
available choices are EvenOddRule and WindingRule. The EvenOddRule constant 
defines a point to be inside a polygon if an infinite ray with the point as origin crosses 
the path an odd number of times. If the point meets these conditions, the server 
draws a corresponding pixel. 


The WindingRule constant defines a point to be inside the polygon if an infinite ray 
with the pixel as origin crosses an unequal number of clockwise and counterclockwise 
directed path segments. A clockwise directed path segment is one that crosses the 
ray from left to right as observed from the pixel. A counterclockwise segment is one 
that crosses the ray from right to left as observed from that point. When a directed 
line segment coincides with a ray, choose a different ray that is not coincident with a 
segment. If the point meets these conditions, the server draws a corresponding pixel. 


For both even odd rule and winding rule, a point is infinitely small, and the path is an 
infinitely thin line. A pixel is inside the polygon if the center point of the pixel is inside, 
and the center point is not on the boundary. If the center point is on the boundary, 
the pixel is inside if and only if the polygon interior is immediately to its right 

(x increasing direction). Pixels with centers along a horizontal edge are a special 
case and are inside if and only if the polygon interior is immediately below 

(y increasing direction). 


Figure 5—5 illustrates fill rules. 


Controls how the server fills an arc. The available choices are the values specified 
by the ArcPieSlice and ArcChord constants. Figure 5-6 illustrates the two modes. 


Specifies the pixmap the server uses for tiling operations. The pixmap must have the 
same root and depth as the graphics context or an error occurs. Clients can use any 
size pixmap for tiling, although some sizes are faster than others. 


Storing a pixmap in a graphics context might or might not result in a copy being 
made. If the pixmap is used later as the destination for a graphics request, the 
change might or might not be reflected in the graphics context. If the pixmap is used 
simultaneously in a graphics request both as a destination and as a tile, the results 
are not defined. 


Specifies the pixmap the server uses for stipple operations. The pixmap must have 
the same root as the graphics context and a depth of one, or an error occurs. For 
stipple operations where the fill style is specified as the FillStippled constant but not 
the FillOpaqueStipple constant, the stipple pattern is tiled in a single plane and acts 
as an additional clip mask. Perform a bitwise AND operation with the clip mask. 
Clients can use any size pixmap for stipple operations, although some sizes are 
faster than others. 


Storing a pixmap in a graphics context might or might not result in a copy being 
made. If the pixmap is used later as the destination for a graphics request, the 
change might or might not be reflected in the graphics context. If the pixmap is 
used simultaneously in a graphics request both as a destination and as a stipple, the 
results are not defined. 


Defines the origin for tiling and stipple operations. Origins are relative to the origin of 
whatever window or pixmap is specified in the graphics request. 


(continued on next page) 
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Member Name 


ts_y_origin 


font 
subwindow_mode 


graphic_exposures 
clip_x_origin 
clip_y_origin 


clip_mask 


dash_offset 


dashes 
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Members of the GC Values Data Structure (MIT C Binding) 


Contents 


Defines the origin for tiling and stipple operations. Origins are relative to the origin of 
whatever window or pixmap is specified in the graphics request. 


Specifies the font that the server uses for text operations. 


Specifies whether inferior windows clip superior windows. The constant 
ClipByChildren specifies that all viewable input-output children clip both source 
and destination windows. The constant Includelnferiors specifies that inferiors clip 
neither source nor destination windows. This results in drawing through subwindow 
boundaries. The semantics of using the constant on a window with a depth of one 
and with mapped inferiors of differing depth is undefined by the core protocol. 


Specifies whether the server informs the client when the contents of a window region 
are lost. 


Defines the x-coordinate of the clip origin. The clip origin specifies the point within 
the clip region that is aligned with the drawable origin. 


Defines the y-coordinate of the clip origin. The clip origin specifies the point within 
the clip region that is aligned with the drawable origin. 


Identifies the pixmap the server uses to restrict write operations to the destination 
that is drawable. The pixmap must have a depth of one and have the same root as 
the graphics context. The clip mask clips only the destination that is drawable, not 
the source drawable. Where a value of one appears in the mask, the corresponding 
pixel in the destination drawable is drawn; where a value of zero occurs, no pixel is 
drawn. Any pixel within the destination drawable that is not represented within the 
clip mask pixmap is not drawn. When a client specifies the value of clip mask as 
None, the server draws all pixels. 


Specifies the pixel within the dash length sequence, defined by the dashes member, 
to start drawing a dashed line. For example, a dash offset of zero starts a dashed 
line as the beginning of the dash line sequence. A dash offset of five starts the line 
at the fifth pixel of the line sequence. Figure 5~9 illustrated dashed offsets. 


Specifies the length, in number of pixels, of each dash. The value of this member 
must be nonzero or an error occurs. 





The default values for the GC values data structure are listed in Table 5—5. 
These values are used in the default graphics context. 
Table 5-5 Default Values for the GC Values Data Structure 


Member Default Value 


function GXcopy 
plane_mask All ones 
foreground 0 
background 1 
line_width 0 
line_style Solid 


(continued on next page) 
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Table 5-5 (Cont.) Default Values for the GC Values Data Structure 


Member Default Value 

cap_style Butt 

join_style Miter 

fill_style Solid 

fill_rule EvenOdd 

arc_mode PieSlice 

tile Pixmap of unspecified size filled with foreground pixel 
stipple Pixmap of unspecified size filled with ones 
ts_x_origin 0 

ts_y_origin 0 

font Can vary 

subwindow_mode ClipByChildren 

graphics_exposures True 

clip_x_origin 0 

clip_y_origin 0 

clip_mask None 

dash_ offset 0 

dash_list 4 (the list [4,4]) 





5.2 GC Mask 


Table 5-6 lists the predefined values for the graphics context bit mask and 
their meaning. 


Table 5-6 GC Mask Bits 
C Predefined Bit 





VAX Predefined Bit Value Value Meaning when Set 
X$M_GC_FUNCTION GCFunction Change the function member 
(default is GXCopy) 
X$M_GC_PLANE_MASK GCPlaneMask Change the plane mask 
member (default is all ones) 
X$M_GC_FOREGROUND GCForeground Change the foreground 
member (default is 0) 
X$M_GC_BACKGROUND GCBackground Change the background 
member (default is 1) 
X$M_GC_LINE_ WIDTH GCLineWidth Change the line width 


member (default is 0) 
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Table 5-6 (Cont.) GC Mask Bits 


VAX Predefined Bit Value 


X$M_GC_LINE_STYLE 


X$M_GC_CAP_STYLE 


X$M_GC_JOIN_STYLE 


X$M_GC_FILL_STYLE 
X$M_GC_FILL_RULE 
X$M_GC.ARC_MODE 


X$M_GC_TILE 


X$M_GC_STIPPLE 


X$M_GC_TILE_STIP_X_ 
ORIGIN 


X$M_TILE_STIP_Y_ 
ORGIGN 


X$M_GC_FONT 
X$M_GC_SUBWINDOW_ 
MODE 


X$M_GC_GRAPHICS_ 
EXPOSURE 


X$M_GC_CLIP_X_ORIGIN 


C Predefined Bit 
Value 


GCLineStyle 


GCCapStyle 


GCJoinStyle 


GCFillStyle 
GCFillRule 
GCArcMode 


GCTile 


GCStipple 


GCTileStipXOrigin 


GCTileStipYOrigin 


GCFont 
GCSubwindowMode 


GCGraphicsExposures 


GCClipXOrigin 


5.2 GC Mask 


Meaning when Set 


Change the line style 
member (default is 
LineSolid) 


Change the cap, endpoint, 
style member (default is 
CapButt) 


Change the join style 
member (default is 
JoinMiter) 


Change the fill style member 
(default is FillSolid) 


Change the fill rule member 
(default is EvenOddRule) 


Change the arc fill mode 
(default is ArcPieSlice) 


Change the tile pixmap 
identifier (default is a pixmap 
of unspecified size filled with 
foreground pixel) 


Change the stipple pixmap 
identifier (default is a pixmap 
of unspecified size filled with 
ones) 

Change the x-coordinate for 
a tile/stipple origin (default 

is 0) 

Change the y-coordinate for 
a tile/stipple origin (default 

is 0) 

Change the font identifier 
Change the subwindow 


mode member (default is 
ClipByChildren) 


Change the graphics 
exposures flag (default 
is True) 


Change the x-coordinate for 
a clip origin (default is 0) 
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5.2 GC Mask 
Table 5-6 (Cont.) GC Mask Bits 
C Predefined Bit 
VAX Predefined Bit Vaiue Value Meaning when Set 
X$M_GC_CLIP_Y_ORIGIN GCClipYOrigin Change the y-coordinate for 
a clip origin (default is 0) 
X$M_GC_CLIP_MASK GCClipMask Change clip mask pixmap 
identifier (default is none) 
X$M_GC_DASH_OFFSET GCDashOffset Change the dash offset 
member (default is 0) 
X$M_GC_DASH_LIST GCDashList Change the dash list 
member (default is 4) 
5.3 Graphics Context Routines 
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CHANGE GC 


Changes any attribute by changing the values in the GC values data structure. 





VAX FORMAT X$CHANGE_GC 
(display, gc_id, g¢c_mask, values_struc) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
gc_mask mask_longword uns longword read reference 
values_struc record x$gc_values read reference 





MITC FORMAT XChangeGC 
(display, gc_id, g¢_mask, values_struc) 


argument 

information XChangeGC (display, gc_id, gc_mask, values_struc) 
Display *display; 
GC gc_id; 


unsigned long gc_mask; 
XGCValues *values_ struc; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 
The identifier of the graphics context to be changed. The graphics context 
identifier was originally returned by DEFAULT GC or CREATE GC, 


gc_mask 
A bit mask that specifies the members in the graphics context to be 
changed. A bitwise logical OR operation of the members sets the mask. 


Table 5-6 lists the predefined values and the description for the g¢e_mask 
argument. 


values_struc 

The GC values data structure that contains the new values. The new 
values specified in ge_mask will be copied into the GC values data 
structure specified by ge_id. 
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DESCRIPTION CHANGE GC uses the mask to identify the values in the graphics context 
to be changed. You identify each member you want to change in that 
mask, then provide the new values for those members in the GC values 
data structure passed in values_struc. 


If the clip mask member is changed by this routine, any previous SET 
CLIP RECTANGLES routine request for the same graphics context is 
overridden by the new clip mask. If the dash offset or dash list members 
are changed by this routine, any previous SET DASHES request for the 
same graphics context is overridden. 


For more information on using the GC values data structure and an 
illustration of this structure, refer to Section 5.1. 





X ERRORS 
VAX Cc Description 
X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 
resource for any cause. 
X$C_BAD_FONT BadFont A value that you specified for a font argument 


does not name a defined font (or, in some 
cases, graphics context). 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

¢ An input-only window is used as a 
drawable. 

* One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

* — An input-only window lacks this attribute. 


X$C_BAD_PIXMAP — BadPixmap A value that you specified for a pixmap 
argument does not name a defined pixmap. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, 
the fuil range defined by the argument’s type 
is accepted. Any argument defined as a set 
of alternatives can generate this error. 
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COPY GC 


Copies the graphics context values from one graphics context data structure 
to another GC values data structure. 





VAX FORMAT xX$COPY_GC 
(display, src_gc_id, g¢c_mask, dst_gc_id) 


argument 


information Argument Usage —Data Type —~—s Access. Mechanism __ 


display identifier uns longword read reference 
src_gc_id identifier uns longword read reference 
gc_mask mask_longword uns longword read reference 
dst_ge_id identifier uns longword read reference 





MITC FORMAT XCopyGC 
(display, src_gc_id, g¢c_mask, dst_gc_id) 


argument 

information XCopyGC (display, src_gc_id, gc_mask, dst_gc_id) 
Display *display; 
GC sre_gc_id, dst_gc_id; 
unsigned long gc_mask; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


src_gc_id 

The identifier of the source graphics context to be copied. The source 
GC values data structure contains the values that will be copied. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


gc_mask 

The bit mask that specifies the members that will be copied from the 
source graphics context to the destination graphics context. Use a bitwise 
OR operation of the predefined values to set the bit mask, or use the mask 
structure. 


Table 5-6 lists the predefined values and descriptions for the gc_mask. 
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dst_gc_id 

The identifier of the destination graphics context that the values from 
the source graphics context are copied to. Only those values specified 
in the gec_mask are changed. This identifier was originally returned by 
DEFAULT GC or CREATE GC. 





DESCRIPTION 


COPY GC copies specific values from one graphics context to another. 
The only values copied are those specified in the ge_mask. The source 
graphics context and the destination graphics context must be of the same 
root and depth. 


The graphics context is an identifier for an internal 
structure/representation and this routine must be used to copy it from 
one variable into others. 





X ERRORS 
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VAX Cc Description 

X$C_BAD_ALLOCG BadAlloc The server did not allocate the requested 
resource for any cause. 

X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a defined 
graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of argumenis has 
the correct type and range but fails to 
match in some other way required by 
the request. 

¢ — An input-only window lacks this attribute. 
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CREATE GC 


Creates a new graphics context for a specific window. Unless specified, the 
members of the graphics context are the default values. 





VAX FORMAT _ gc _id_return = X$CREATE_GC 
(display, drawable_id, g¢c_mask, values_struc) 


argument 


information Argument Usage —~—~—~—~S@DataType +—=—~—«Access_-~=s« Mechanism 


gc_id_return identifier uns longword write value 

display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_mask mask_longword uns longword read reference 
values_struc record x$gc_values read reference 





MITC FORMAT gc _id_return = XCreateGC 
(display, drawable_id, g¢_mask, values_struc) 





argument 
information GC XCreateGC (display, drawable_id, gc_mask, values_struc) 
Display *display; 
Drawable drawable _id; 
unsigned long gc_mask; 
XGCValues *values_struc; 
RETURNS gc_id_return 


The identifier of the new graphics context is returned. 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) to create the new 
graphics context for. 
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CREATE GC 


gc_mask 

The bit mask that specifies the values within the GC values data structure 
that are different from the default values. The values that are different 
from the default values are specified in values_struc. Do a bitwise OR 
operation with the predefined values to set the mask. 


Table 5—6 lists the predefined values and descriptions for the g¢_mask. 


values_struc 
The GC values data structure that specifies nondefault values for the new 
graphics context. 


For more information about this data structure, see the Section 5.1. 





DESCRIPTION 


CREATE GC creates a new graphic context for use with a specified pixmap 
or window (drawable). It returns an identifier for the new graphics 
context. Use the identifier to reference the graphics context in any 
subsequent routines. 


If you need to use nondefault values, use this routine. To specify a 
nondefault value, set the appropriate bit in ge_mask. Then, specify 

the value you want in the appropriate member in values_struc. If you do 
not set the bit, the value is not changed. 


Once created, you can change graphic context values with the CHANGE 
GC or individual SET routines. You can also copy the values from one 
graphics context to another one using the COPY GC routine. 


You can use a default graphics context if the default values are valid 
for your program. Use the DEFAULT GC to return the identifier of the 
default graphics context. The default values are listed in Section 5.1. 


When you are done with the graphics context, be sure to call FREE GC to 
free the storage associated with the graphics context. 





X ERRORS 
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VAX Cc Description 
X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 


resource for any cause. 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

X$C_BAD_FONT BadFont A value that you specified for a font 
argument does not name a defined font 
(or, in some cases, graphics context). 


VAX 
X$C_BAD_MATCH 


X$C_BAD_PIXMAP 


Cc 


BadMatch 


BadPixmap 
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CREATE GC 


Description 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 


A value that you specified for a pixmap 
argument does not name a defined 
pixmap. 
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FREE GC 


Frees a specified graphics context. 





VAX FORMAT X$FREE_GC (display, gc_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 





MITC FORMAT XFreeGC (display, gc_id) 


argument 

information XFreeGC (display, gc_id) 
Display *display; 
GC gc_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context to be freed. This must be an 
identifier that was originally returned by CREATE GC or COPY GC; it 
cannot be the default graphics context identifier. 





DESCRIPTION _ FREE GC destroys a specified graphics context, and frees the storage 
associated with the graphics context as well. 


You cannot free the default GC values data structure; you can free only 
those created with CREATE GC or COPY GC. Therefore, you cannot 
specify the identifier of the default graphics context in ge_id. 





X ERRORS 
VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 
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GCONTEXT FROM GC 


Obtains the graphics context resource identifier for a specified graphics 
context. 





VAX FORMAT — gc_resource_id_return = X$CREATE_GC (gc_id) 


argument 


information Ti aa ae ao 


gc_resource_id_return identifier uns longword write value 
gc_id_return identifier uns longword read reference 





MITC FORMAT  gc_resource_id_return=XCreateGC (gc_id) 





argument 

information GContext XGContextFromGC (gc_id) 
GC gc_id; 

RETURNS gc_resource_id_return 


The graphics context resource identifier for the specified graphics context. 





ARGUMENTS _ gc _id 


The graphics context for which you want to obtain the resource identifier. 





DESCRIPTION =GCONTEXT FROM GC obtains the graphics context resource identifier for 
a specified graphics context. 
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QUERY BEST SIZE 


Obtains the optimal size for improved server performance for the cursor, the 
tile pattern, or the stipple pattern. 





VAX FORMAT _ status_return = X$QUERY_BEST_SIZE 
(display, class, drawable_id, width, height, 
width_return, height_return) 
argument 
information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
display identifier uns longword read reference 
class longword longword read reference 
drawabie_id identifier uns longword read reference 
width uns longword uns longword read reference 
height uns longword —_ uns longword read reference 
width_return uns longword —_uns longword write reference 
height_return uns longword uns longword write reference 





MIT C FORMAT .sstatus_return = XQueryBestSize 
(display, class, drawable_id, width, height, 
width_return, height_return) 


argument 
information Status XQueryBestSize(display, class, drawable_id, width, height, 
width_return, height_return) 

Display *display; 

int class; 

Drawable drawable_id; 

unsigned int width, height; 

unsigned int *width_return, *height_return; 





RETURNS status_return 


Specifies whether the routine completed successfully. 


C only 


This argument returns 1 if the routine completes successfully, and zero if 
it does not complete successfully. 
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VAX only 


This argument returns one of the following values. 


Value Description 


X$_ERRORREPLY Error received from the server. 





SS$_ NORMAL Success. 

ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 
class 


The item to determine the best size for. The predefined values for class 
are as follows: 


VAX Cc Description 

X$C_TILE_SHAPE TileShape Determine the best size for the tile pattern. 
X$C_STIPPLE_ StippleShape Determine the best size for the stipple 
SHAPE pattern. 

X$C_CURSOR_ CursorShape Determine the best size for the cursor. 
SHAPE 


Other values specified in this argument are not valid. 


drawable_id 

The identifier of the drawable (window or pixmap) associated with the 
item to determine the best size for. The drawable_id argument cannot 
refer to an input-only window for a tile or a stipple, otherwise the routine 
cannot complete successfully. 


width 


The width, in pixels, of the item to determine the best size for. The width 
and height determine the desired area of the tile, stipple, or cursor. 


height 
The height, in pixels, of the item to determine the best size for. The height 
and width determine the desired area of the tile, stipple, or cursor. 


width_return 

A pointer to the optimal width, in pixels, of the item returned by the 
server. The width and height determine the best size closest to the area 
specified for the tile, stipple, or cursor that maximizes server performance. 


height_return 

A pointer to the optimal height, in pixels, of the item returned by the 
server. The width and height determine the best size that is closest to 
the area specified for the tile, stipple, or cursor that maximizes server 
performance. 
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DESCRIPTION QUERY BEST SIZE obtains the optimal size for a tile, stipple, or cursor 
pattern that maximizes server performance. For a tile and stipple, the 
best size is the size that can be tiled or stippled in the least amount of 
time. For a cursor, the best size is the largest cursor that can be fully 
displayed. 


You specify the desired size of the tile, stipple, or cursor in the width and 
height arguments. The server returns the best size that is closest to the 
size you specified for the item in the width_return and height_return 
arguments. 


You can also use the QUERY BEST TILE, QUERY BEST STIPPLE and 
QUERY BEST CURSOR routines to determine the best sizes for these 
items. 





X ERRORS 


VAX Cc Description 





X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

« — An input-only window lacks this 
attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Uniess a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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QUERY BEST STIPPLE 


Obtains the optimal size for improved server performance for a stipple pattern. 





VAX FORMAT _ sitatus_return = X$QUERY_BEST_STIPPLE 
(display, drawable_id, width, height, width_return, 
height_return) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
width uns longword uns longword read reference 
height uns longword uns longword read reference 
width_return uns longword uns longword write reference 
height_return uns longword uns longword write reference 





MiT C FORMAT -sstatus_return = XQueryBestStipple 
(display, drawable_id, width, height, width_return, 
height_return) 





argument 
information Status XQueryBestStipple(display, drawable_id, width, height, 
width_return, height_return) 
Display *display; 
Drawable drawable id; 
unsigned int width, height; 
unsigned int *width_return, *height_return; 
RETURNS status_return 


Specifies whether the routine completed successfully. 


C only 


This argument returns 1 if the routine completes successfully, and zero if 
it does not complete successfully. 
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VAX only 


This argument returns one of the following values. 


Value Description 


X$_ERRORREPLY Error received from the server. 
SS$_NORMAL Success. 





ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the drawable (window or pixmap) associated with the 
stipple pattern. The drawable refers to the screen and possibly the window 
class and depth that the stipple pattern will be used on. The 
drawable_id argument cannot refer to an input-only window, otherwise 
the routine cannot complete successfully. 


width 


The width, in pixels, of the stipple pattern to determine the best size for. 
The width and height determine the desired area of the stipple. 


height 
The height, in pixels, of the stipple pattern to determine the best size for. 
The height and width determine the desired area of the stipple. 


width_return 

A pointer to the optimal width, in pixels, of the stipple returned by the 
server. The width and height determine the best size that is closest to the 
size specified for the stipple that maximizes server performance. 


height_return 

A pointer to the optimal height, in pixels, of the stipple returned by the 
server. The width and height determine the best size that is closest to the 
size specified for the stipple that maximizes server performance. 





DESCRIPTION 
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QUERY BEST STIPPLE obtains the optimal size for a stipple pattern 
that maximizes server performance. The best size is the size that can be 
stippled in the least amount of time. 


You specify the desired size of the stipple in the width and height 
arguments. The server returns the best size that is closest to the size 
specified in the width_return and height_return arguments. 


You can also use the QUERY BEST SIZE routine to determine the best 
size for a stipple pattern. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


¢ In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 
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QUERY BEST TILE 


Obtains the optimal size for improved server performance for a tile pattern. 





VAX FORMAT _ siatus_return = X$QUERY_BEST_TILE 
(display, drawable_id, width, height, width_return, 
height_return) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
width uns longword uns longword read reference 
height uns longword uns longword read reference 
width_return uns longword uns longword write reference 
height_return uns longword uns longword read reference 





MIT C FORMAT -sstatus_return = XQueryBestTile 
(display, drawable_id, width, height, width_return, 
height_return) 





argument 
information Status XQueryBestTile(display, drawable_id, width, height, 
width_return, height _return) 
Display *display; 
Drawable drawable_id; 
unsigned int width, height; 
unsigned int *width_return, *height_return; 
RETURNS status_return 


Specifies whether the routine completed successfully. 


VAX only 


This argument returns one of the following values: 
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Value Description 


X$_ERRORREPLY Error received from the server. 
SS$_NORMAL Success. 


C only 


This argument returns 1 if the routine completes successfully, and zero if 
it does not complete successfully. 





ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the drawable (window or pixmap) associated with the tile 
pattern. The drawable refers to the screen and possibly the window class 
and depth that the tile pattern will be used on. The drawable_id cannot 
refer to an input-only window, otherwise the routine cannot complete 
successfully. 


width 


The width, in pixels, of the tile pattern to determine the best size for. The 
width and height determine the desired area of the tile. 


height 
The height, in pixels, of the tile pattern to determine the best size for. The 
height and width determine the desired area of the tile. 


width_return 

A pointer to the optimal width, in pixels, of the tile returned by the server. 
The width and height determine the best size that is closest to the size 
specified for the tile that maximizes server performance. 


height_return 

A pointer to the optimal height, in pixels, of the tile returned by the server. 
The width and height determine the best size that is closest to the size 
specified for the tile that maximizes server performance. 





DESCRIPTION 


QUERY BEST TILE obtains the optimal size for a tile pattern that 
maximizes server performance. The best size is the size that can be 
tiled in the least amount of time. 


You specify the desired size of the tile in the width and height 
arguments. The server returns the best size, which is closest to the 
size specified, in the width_return and height_return arguments. 


You can also use the QUERY BEST SIZE routine to determine the best 
size for a tile pattern. 


Graphics Context Routines 
QUERY BEST TILE 





X ERRORS 


VAX c Description 


X$C_BAD_DRAWABLE  BadDrawabie A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 
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SET ARC MODE 


Sets the arc mode to the value specified. 





VAX FORMAT X$SET_ARC_MODE 
(display, gc_id, arc_mode) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
arc_mode longword longword read reference 





MITC FORMAT XSetArcMode 
(display, gc_id, arc_mode) 


argument 

information XSetArcMode (display, gc_id, arc_mode) 
Display *display; 
GC gc_id; 


int arc_mode; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the arc mode member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


arc_mode 
Specifies how an arc will be filled in a subsequent graphics request. The 
predefined values for arc_mode are as follows: 


VAX Cc Description 


X$C_ARC_CHORD ArcChord Only the chord area of the arc is filled. 


X$C_ARC_PIE_SLICE ArcPieSlice The triangular area defined by the arc 
center and the arc endpoints is filled. 


Other values specified in this argument are not valid. 
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DESCRIPTION SET ARC MODE changes the value for the arc mode member in the 
graphics context data structure. The graphics context identifier was 
originally returned by DEFAULT GC or CREATE GC. 


The arc mode specifies which portion of an arc to draw: either a pie slice 
or a chord. Refer to Figure 5-8 for an illustration of the arc fill options. 


Figure 5—8 Arc Fill Options 


Chord 


Pie Slice 
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You can also use CHANGE GC to change the arc mode. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE  BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET BACKGROUND 


Sets the background color index to the value specified. 





VAXFORMAT X$SET_BACKGROUND 
(display, gc_id, background) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
background uns longword uns longword read reference 





MITC FORMAT XSetBackground 
(display, gc_id, background) 


argument 

information XSetBackground(display, gc_id, background) 
Display *display; 
GC gc_id; 


unsigned long background; 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the background member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


background 
The new value of the background member. The background value is a color 
index to a color map containing the color definition for the background. 





DESCRIPTION SET BACKGROUND changes the value for the background member in the 
GC values data structure. The graphics context identifier was originally 
returned by DEFAULT GC or CREATE GC. 


The background member value is the color index to a color map containing 
the color definition for the background. The color index you specify in 
background must have been returned by one of the color routines 
(ALLOC COLOR CELLS, ALLOC COLOR PLANES, ALLOC COLOR, 

or ALLOC NAMED COLOR) or by one of the display information routines 
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(BLACK PIXEL or WHITE PIXEL). For more information on working with 
colors, see Chapter 12. 

You can also use SET STATE or CHANGE GC to change the background. 
When you use SET STATE, you must also change the foreground, function, 
and plane mask members. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


Graphics Context Routines 
SET CLIP MASK 


SET CLIP MASK 


Sets the clip mask of a graphics context to the specified pixmap. 





VAX FORMAT X$SET_CLIP_MASK 
(display, gc_id, pixmap_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gce_id identifier uns longword read reference 
pixmap_id identifier uns longword read reference 





MITC FORMAT XSetClipMask 
(display, gc_id, pixmap_id) 


argument 

information XSetClipMask (display, gc_id, pixmap_id) 
Display *display; 
GC gc_id; 


Pixmap pixmap_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 
The identifier of the graphics context where the clip mask will be changed. 
This identifier was originally returned by CREATE PIXMAP. 


pixmap_id 


The identifier of the pixmap containing the new clip mask. 





DESCRIPTION SET CLIP MASK sets the clip mask of a graphics context to the specified 
pixmap. Use a clip mask when you want to clip a nonrectangular area. 
The area clipped out is represented by zeros; the area maintained is 
represented by ones. 


If you specify None, all pixels are drawn. 


After you identify a pixmap as a clip mask, you should not write into that 
pixmap. Otherwise, the results are undefined. 
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When you want to clip a rectangular area, use SET CLIP RECTANGLES. 
You can also change the clip mask with CHANGE GC. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_MATCH  BadMatch Possible causes are as follows: 


* Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by the 


request. 
* — An input-only window lacks this attribute. 
X$C_BAD_VALUE  BadValue Some numeric values fall outside the range 


of values accepted by the request. Uniess a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET CLIP ORIGIN 


Changes the clip origin members in the specified graphics context. 





VAX FORMAT X$SET_CLIP_ORIGIN 
(display, gc_id, clip_x_coord, clip_y_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
clip_x_coord longword longword read reference 
clip_y_coord longword longword read reference 





MITC FORMAT XSetClipOrigin 
(display, gc_id, clip_x_coord, clip_y_coord) 


argument 

information XSetClipOrigin(display, gc_id, clip _x_coord, clip _y_ coord) 
Display *display; 
GC ge_id; 


int clip_x_coord, clip_y coord; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where clip origin coordinates will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


clip_x_coord 


The new x-coordinate of the clip origin. The default value is 0. 


clip_y_coord 
The new y-coordinate of the clip origin. The default value is 0. 
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DESCRIPTION = SET CLIP ORIGIN changes the x- and y-coordinate values for the clip 
origin. The clip origin is aligned with the origin of the window or pixmap 
(drawable) involved in the clip operation. The graphics context identifier 
was originally returned by DEFAULT GC or CREATE GC. 


You can also change the clip origin members with CHANGE GC. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 
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SET CLIP RECTANGLES 


Changes the clip origin members in the specified graphics context and 
specifies rectangular clip areas. 





VAX FORMAT X$SET_CLIP_RECTANGLES 
(display, gc_id, clip_x_coord, clip_y_coord, rectangles, 
num_rectangles, ordering) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gce_id identifier uns longword read reference 
clip_x_coord longword longword read reference 
clip_y_coord longword longword read reference 
rectangles record x$rectangle read reference 
num_rectangles —longword longword read reference 
ordering longword longword read reference 





MITC FORMAT XSetClipRectangles 
(display, gc_id, clip_x_coord, clip_y_coora, rectangles, 
num_rectangles, ordering) 





argument 
information XSetClipRectangles (display, gc_id, clip_x_coord, clip_y_coord, 
rectangles, num_rectangles, ordering) 
Display *display; 
GC gc_id; 
int clip_x coord, clip _y coord; 
XRectangle rectangles[]; 
int num_rectangles; 
int ordering; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the clip origin will be changed. 
The graphics context identifier was originally returned by DEFAULT GC 
or CREATE GC. 


Graphics Context Routines 
SET CLIP RECTANGLES 
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clip_x_coord 
The new x-coordinate of the clip origin. The default value is 0. The x- and 
y-coordinates define the clip origin. 


clip_y_coord 
The new y-coordinate of the clip origin. The default value is 0. The x- and 
y-coordinates define the clip origin. 


rectangles 


A pointer to an array of rectangle data structures where each element 
defines a clip area. Within each rectangle data structure, you specify the 
rectangle size (width and height) and position of the upper left corner 

(x- and y-coordinates). The x- and y-coordinates are interpreted relative to 
the clip origin. The array length is specified by num_rectangles. 


num_rectangles 
The number of rectangles to be specified in the graphics context. This 
value defines the length of the array in rectangles. 


ordering 
Specifies the ordering relationship of the clip rectangles. 


The predefined values for ordering are as follows: 


VAX Cc Description 

X$C_UN_SORTED UnSorted Rectangles are in arbitrary order. 

X$C_Y_SORTED YSorted Rectangles are nondecreasing in the 
y-coordinate of their origin. 

X$C_Y_X_SORTED YXSorted Rectangles are nondecreasing in the 


y-coordinate of their origin. For 
rectangles with an equal y-coordinate, 
they are nondecreasing in the x- 
coordinate of their origin. 


X$C_Y_X_BANDED YXBanded Rectangles are nondecreasing in the 
y-coordinate of their origin for every 
possible y scan line, all rectangles that 
include that scan line have an identical 
y-coordinate. 


Other values specified in this argument are not valid. 


Server performance improves if the rectangles are ordered (UnSorted 
would result in the lowest performance, then YSorted, then YXSorted, 
with YXBanded having the best performance). However, if the rectangles 
are not in the same order as specified in this argument, the graphics 
results will be undefined. 
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DESCRIPTION 


SET CLIP RECTANGLES changes the clip origin in the specified graphics 
context. It also specifies the size and position of rectangular clip areas. 


The output is clipped to remain contained within the rectangles. The 

clip origin is aligned with the origin of the destination drawable that is 
specified in a graphics request. The coordinates are interpreted relative to 
the clip origin. The rectangles should not intersect, or graphics results will 
be undefined. 


If you know the correct order of the rectangles, you can specify the order 
in ordering to improve server performance. If you specify an incorrect 
order, the graphics results are undefined. 


If you want to effectively disallow any output, the list of rectangles in 
rectangles can be empty. 


If you want to clip a nonrectangular area, use a clip mask. Use the 
SET CLIP MASK routine to specify the pixmap in the graphics context 
containing the clip mask. 


You cannot use CHANGE GC to specify clip rectangles, although you can 
use CHANGE GC to specify the clip origin. 





X ERRORS 


VAX Cc Description 

X$C_BAD_ALLOC  BadAlloc The server did not allocate the requested 
resource for any cause. 

X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument's type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET DASHES 


Changes the values for the dash offset and the dash list. 





VAX FORMAT X$SET_DASHES 
(display, gc_id, dash_offset, dash_list, dash_list_len) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
dash_offset longword longword read reference 
dash_list byte byte read reference 
dash_list_len longword longword read reference 





MITC FORMAT XSetDashes 
(display, gc_id, dash_offset, dash_list, dash_list_len) 


argument 

information XSetDashes (display, gc_id, dash_offset, dash_list, dash_list_len) 
Display *display; 
GC gc_id; 


int dash offset; 
char dash_list[]; 
int dash_list_len; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the dash members will be 
changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


dash_offset 

The pixel within the dash length sequence, defined in dash_list, to start 
drawing a dashed line. A dash_offset of zero would start at the beginning 
of the dash length sequence. A dash_offset of 5 would start at the fifth 
pixel. Refer to Figure 5-9. 
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dash_list 

A pointer to an array that lists the length, in number of pixels, for each 
dash. The initial and alternating elements in the array (elements 0, 2, 
4, and so forth) are the even dashes. The other elements in the array (in 
other words, elements 3, 5, and so forth) reference the odd dashes. 


The values of all elements must be nonzero. The number of elements (in 
other words, the length of the array) is defined by n. The default value 
is 4. 

This argument cannot be empty, otherwise the routine will not complete 
successfully. 


dash_list_len 
The number of dash lengths specified. This value defines the length of the 
array in dash_list. 





DESCRIPTION 


SET DASHES changes the dash members in the specified graphics context. 


The dash list specifies the length, in pixels, of each element in the dash 
line. For example, the dash list array might have the following values: 


Array Element Value 
5 

10 

3 

5 

10 

3 
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The first dash in the line (even dash 0) is 5 pixels long, the second dash in 
the line is 10 pixels long (odd dash 1), and so forth. Refer to Figure 5-9. 
Figure 5-9 Dash Offset and Dash List 


Dash List: 5,10,3,5,10,3 


Dash Offset = 0 
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The actual dash line is likely to have more dashes than are represented in 
the dash list. In this case, the list is simply reread so that the next dash 
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has the length specified in array element 0, and so forth. The dash list 
array will continue to be read until the dash line is complete. 


You can specify an odd number of dash lengths in the dash list. For 
example, the dash list array might have the following values: 


Array Element Value 
0 5 
1 10 
2 5 


If this dash line has nine dashes, the lengths are as shown in 
Figure 5-10. 


Figure 5-10 Odd Dash List 


Dash List 5, 10, 5 





Even Even Even Even Even 
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The dash offset specifies where to start reading, within the dash list, the 
lengths of the dashes. For example, if the dash offset is 3, the first length 
in the dash list is the third from the start. In the preceding dash list 
example, a dash offset of 3 means that the length of the first dash is 2. 


A dashed line is continuous through a specified path. When dashed lines 
are joined, they are joined according to the join style specified in the 
graphics context. When a dashed line is ended (in other words, a cap_style 
from the graphics context is applied to an endpoint), the dash line is reset 
to the dash offset. 





X ERRORS 
VAX Cc Description 
X$C_BAD_ALLOC  BadAlloc The server did not allocate the requested 
resource for any cause. 
X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a defined 
graphics context. 


X$C_BAD_ VALUE  BadValue Some numeric values fall outside ihe range 
of values accepted by the requesi. Unless a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET FILL RULE 


Sets the fill rule in the graphics context to the value specified. 





VAX FORMAT X$SET_FILL_RULE 
(display, gc_id, fill_rule) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
fill_rule longword longword read reference 





MITC FORMAT XSetFillRule 
(display, gc_id, fill_rule) 


argument 

information XSetFillRule(display, gc_id, fill_rule) 
Display *display; 
GC gc_id; 


int fill_rule; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the fill rule member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


fill_rule 

The fill rule that you want to set for the specified graphics context. The 
fill rule specifies which pixels are considered to be inside of a polygon for 
a FILL POLYGON routine. Those inside the polygon are then displayed 
creating the fill. There are two predefined values: 
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VAX 
X$C_EVEN_ODD_RULE 


X$C_WINDING_RULE 


Cc 
EvenOddRule 


WindingRule 


Description 


A pixel is considered to be inside 
the polygon when a ray drawn 
from the pixel intersects the 
polygon lines an odd number of 
times. If the ray drawn from the 
pixel intersects an even number 
of times, the pixel is not drawn. 


A pixel is considered to be 
inside when a ray with the 

point as origin crosses an 
unequal number of clockwise 
and counterclockwise directed 
path segments. A clockwise line 
is one that crosses the ray from 
left to right as observed from the 
origin. A counterclockwise line is 
one which crosses the ray from 
right to left as observed from the 
origin. 


Refer to Figure 5-11 for an illustration of the Even Odd and Winding 


options. 
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Figure 5-11 Fill Rules 
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DESCRIPTION ~— SET FILL RULE changes the value for the fill rule in the graphics context 
data structure. 
You can also use CHANGE GC to change the fill rule. 
X ERRORS 
VAX Cc Description 
X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 
X$C_BAD_VALUE _ BadValue Some numeric values fall outside the range 


of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET FILL STYLE 


Sets the fill style in the graphics context to the value specified. 





VAX FORMAT X$SET_FILL_STYLE 
(display, gc_id, fill_style) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
fill_style longword longword read reference 





MITC FORMAT XSetFillStyle 
(display, gc_id, fill_style) 


argument 

information XSetFillStyle(display, gc_id, fill_style) 
Display *display; 
GC gc_id; 


int fill_style; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the fill style member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


fill_style 

The fill style for the space within the bounding box of a line, the even 
dash of an On Off Dash or Double Dash line, for an odd dash of a Double 
Dash line, for text lines, and for all fill requests. The predefined values for 
fill_style are as follows: 
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VAX Cc Description 





X$C_FILL_SOLID FillSolid Use the color index specified by 
the graphics context foreground 
member for each pixel in the fill 
area. For the odd dash, use the 
color index specified by the graphics 
context background member for 
each pixel in the odd dash fill area. 


X$C_FILL_TILED FillTiled Use the tile pattern as specified by 
the graphics context tile member. 

X$C_FILL_OPAQUE_ FillOpaqueStippled Use the stipple pattern as specified 

STIPPLED by the graphics context stipple 


member. Where the value of 1 
appears in the stipple pattern, use 
the foreground color index for the 
corresponding pixel; where the 
value of zero appears, use the 
background color index for the 
corresponding pixel. 


X$C_FILL_STIPPLED FillStippled Use the stipple pattern as specified 
by the graphics context. Where 
the value of 1 appears in the 
stipple pattern, you can write to 
the corresponding pixel; where the 
value of zero appears, you cannot 
write to the corresponding pixel. 
Use the background color index for 
the corresponding pixel. 


Other values specified in this argument are not valid. 





DESCRIPTION SET FILL STYLE changes the fill style in the graphics context data 
structure. 


The fill style specifies how to fill in bounding boxes in lines or figures. 
You can also use CHANGE GC to change the fill style. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE _ BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET FONT 


Changes the identifier of the font in the specified graphics context. 





VAX FORMAT X$SET_FONT 
(display, gc_id, font_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
font_id identifier uns longword read reference 





MITC FORMAT XSetFont 
(display, gc_id, font_id) 


argument 

information XSetFont (display, gc_id, font_id) 
Display *display; 
GC gc_id; 


Font font_id; 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the font identifier will be 
changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


font_id 
The identifier of the font that will be set in the graphics context. The font 
identifier was originally returned by GET FONT. 





DESCRIPTION _— SET FONT changes the font identifier in the graphics context. Before 
you change the font identifier, you must have already loaded the font and 
generated a font identifier using GET FONT and LOAD FONT. 


You can also use CHANGE GC to change the font identifier. 
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X ERRORS 


VAX 
X$C_BAD_ALLOC 


X$C_BAD_FONT 


X$C_BAD_GC 


Cc 
BadAlloc 


BadFont 


BadGC 


Description 


The server did not allocate the requested 
resource for any cause. 

A value that you specified for a font argument 
does not name a defined font (or, in some 
cases, graphics context). 

A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 
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SET FOREGROUND 


Sets the foreground color index to the value specified. 





VAX FORMAT X$SET_FOREGROUND 
(display, gc_id, foreground) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
foreground uns longword uns longword read reference 





MITC FORMAT XSetForeground 
(display, gc_id, foreground) 


argument 

information XSetForeground(display, gc_id, foreground) 
Display *display; 
GC gc_id; 


unsigned long foreground; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the foreground member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


foreground 

The new value of the foreground member. The foreground value is a color 
index to a color map containing the color definition for the foreground 
color. The default value is zero. 





DESCRIPTION SET FOREGROUND changes the value for the foreground in the GC 
values data structure. 


The foreground member value is the color index to a color map containing 
the color definition for the foreground. The color index you specify in 
foreground must have been returned by one of the color routines (ALLOC 
COLOR CELLS, ALLOC COLOR PLANES, ALLOC COLOR, or ALLOC 
NAMED COLOR) or by one of the display information routines (BLACK 
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PIXEL or WHITE PIXEL). For more information about working with 
colors, see Chapter 12. 
You can also use SET STATE or CHANGE GC to change the foreground 


member. When you use SET STATE, you must also change the 
background, function, and plane mask members. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 
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SET FUNCTION 


Sets the function value to the value specified. 





VAX FORMAT X$SET_FUNCTION 
(display, gc_id, function) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
function longword longword read reference 





MITC FORMAT XSetFunction 
(display, gc_id, function) 


argument 

information XSetFunction(display, gc_id, function) 
Display *display; 
GC gc_id; 


int function; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the function member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


function 

The new value for the function member of the graphics context. The 
function member describes how the new destination bits are to be 
computed from the source bits and the old destination bits. Table 5-7 
lists the valid values for function. The default value is 3 for GX Copy. 
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Table 5-7 Graphics Context Codes for Function Member 





Hex 
Value 


oO 


Tmooownreadg aon oonouorkh won = 


VAX Function Name 


X$C_GX_CLEAR 
X$C_GX_AND 
X$C_GX_AND_REVERSE 
X$C_GX_COPY 
X$C_GX_AND_INVERTED 
X$C_GX_NOOP 
X$C_GX_XOR 
X$C_GX_OR 
X$C_GX_NOR 
X$C_GX_EQUIV 
X$C_GX_INVERT 
X$C_GX_OR_REVERSE 


X$C_GX_COPY_INVERTED 


X$C_GX_OR_INVERTED 
X$C_GX_NAND 
X$C_GX_SET 


C Function 

Name Operation 

GXclear 0 

GXand src AND dst 
GXandReverse src AND NOT dst 
GXcopy src 

GXandInverted (NOT src) AND dst 
GXnoop dst 

GXxor src XOR dst 

GXor src OR dst 

GXnor (NOT src) AND NOT dst 
GXequiv (NOT src) XOR dst 
GXinvert NOT dst 

GXorReverse src OR NOT dst 
GXcopyinverted NOT src 

GXorlnverted (NOT src) OR dst 
GXnand (NOT src) OR NOT dst 
GXset 1 





DESCRIPTION 


SET FUNCTION changes the value for the function member in the GC 
values data structure. The function describes how the new destination bits 
are computed from the source bits and the old destination bits. 


You can also change the function using SET STATE or CHANGE GC. 
When you use SET STATE, you also change the foreground, background, 
and plane mask. 





X ERRORS 


VAX Cc 
X$C_BAD_GC 


X$C_BAD_VALUE 


BadGC 


BadValue 


Description 


A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


Some numeric values fall outside the range 

of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET GRAPHICS EXPOSURES 


Changes the graphics exposures. 





VAX FORMAT X$SET_GRAPHICS EXPOSURES 
(display, gc_id, graphics_exposures) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
graphics_exposures boolean uns longword read reference 





MITC FORMAT XSetGraphicsExposures 
(display, gc_id, graphics_exposures) 


argument 

information xSetGraphicsExposures (display, gc_id, graphics_exposures) 
Display *display; 
GC gc_id; 


Boolean graphics_exposures; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the graphics exposures 
member will be changed. The graphics context identifier was originally 
returned by DEFAULT GC or CREATE GC. 


gor aphics_exposur es 

A graphics exposures member that specifies whether to generate graphics 
exposures events when using the COPY AREA or COPY PLANE routines. 
When true, the events are generated. When false, the events are not 
generated. 





DESCRIPTION SET GRAPHICS EXPOSURES changes the value for the graphics 
exposures member in the graphics context. 


You can also use CHANGE GC to change graphics exposures. 
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X ERRORS 
VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE  BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the arguments type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET LINE ATTRIBUTES 


Changes the line drawing members in the graphics context. 





VAX FORMAT X$SET_LINE_ATTRIBUTES 
(display, gc_id, line_width, line_style, cap_style, 
join_style) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
ge_id identifier uns longword read reference 
line_width longword longword read reference 
line_style longword longword read reference 
cap_style longword longword read reference 
join_style longword longword read reference 





MITC FORMAT XSetLineAttributes 
(display, gc_id, line_width, line_style, cap_style, 
join_style) 


argument 
information XSetLineAttributes (display, gc_id, line width, line_style, 
cap_style, join_style) 


Display *display; 

GC gc_id; 

unsigned int line width; 
int line style; 

int cap_style; 

int join_style; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the line attributes will be 
changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 
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line_width 

Specifies the line width member. The line width defines how wide lines are 
drawn, in terms of number of pixels. The default value is zero, specifying 
the special case of a line one pixel wide. The maximum value for this 
member is limited by the size of the window you are working in. Refer to 
the VMS DECwindows Xlib Programming Volume for more information on 
line widths. 


line_style 
Specifies the line style member. Line style defines the pattern of a line. 
The predefined values for line_style are as follows: 


VAX Cc Description 

X$C_LINE_ SOLID LineSolid A solid line 

X$C_LINE_ LineDoubleDash A dashed line where the even dashes are 
DOUBLE_DASH different from the odd dashes 
X$C_LINE_OFF_ LineOnOffDash A dashed line where the even dashes are 
DASH drawn, but the odd dashes are empty 


Other values specified in this argument are not valid. 


The default value specifies the Solid pattern. Refer to Figure 5-12 for an 
illustration of these styles. 


Figure 5-12 Line Styles 
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cap_style 
Specifies the cap style member, which defines how the endpoints of a path 
are drawn. The predefined values for cap_style are as follows: 


VAX Cc Description 

X$C_CAP_NOT_ _CapNotLast A square endpoint with no projection. This style 
LAST is used for line widths of zero or 1 only. 
X$C_CAP_BUTT CapBuitt A square endpoint, where the square is 


perpendicular to the slope of the line, with 
no projection beyond the endpoint. 
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VAX Cc Description 
X$C_CAP_ CapRound A circular arc endpoint. The diameter of the arc 
ROUND is equal to the line width. The arc is centered 


on the endpoint. This style is not used for line 
widths of zero or 1. 


X$C_CAP_ CapProjecting A square endpoint with the path extended 

PROJECTING beyond the endpoint. The distance extended is 
equal to one-half the line width. This style is not 
used for line widths of zero or 1. 


Other values specified in this argument are not valid. 


The default value is the Butt pattern. Refer to Figure 5-13 for an 
illustration of these styles. 


Figure 5-13 Cap Styles 
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join_style 
The join style. The join style specifies how corners are drawn for wide 
lines. The predefined values for join_style are as follows: 
VAX Cc Description 
X$C_JOIN_MITER JoinMiter The outer edges of the lines are extended to 


meet at an angle. 


X$C_JOIN_ROUND — JoinRound A circular arc corner. The diameter of the arc 
is equal to the line width. The arc is centered 
on the point where the two lines join. 


X$C_JOIN_BEVEL JoinBevel A square corner with the triangular notch of 
the corner filled in. 


Other values specified in this argument are not valid. 
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The default value is the Miter pattern. Refer to Figure 5-14 for an 
illustration of these styles. 


Figure 5-14 Join Styles 
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DESCRIPTION 


SET LINE ATTRIBUTES changes the values for the following line drawing 
members in the specified graphics context: 


¢ Line width 
e¢ Line style 
¢ Cap style (how endpoints are drawn) 


¢ Join Style (how corners are drawn) 


The patterns for the line style, cap style, and join style are illustrated 
in the argument descriptions. The join style is used only when lines are 
joined within a single graphics request. 


You can also change the line attributes with CHANGE GC. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE __ BadValue Some numeric values fall outside the range 
of values accepted by the request. Untess a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET PLANE MASK 


Sets the plane mask to the value specified. 





VAX FORMAT X$SET_PLANE_MASK 
(display, gc_id, plane_mask) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
plane_mask mask_longword uns longword read reference 





MITC FORMAT XSetPlaneMask 
(display, gc_id, plane_mask) 


argument 

information XSetPlaneMask(display, gc_id, plane_mask) 
Display *display; 
GC gc_id; 


unsigned long plane_mask; 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the plane mask member will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


plane_mask 
A bit mask that specifies which planes will be modified. 


The plane mask specifies which planes of the display will be modified. For 
monochrome displays, there is only one plane. Within the plane mask, the 
least significant bit represents this plane. For displays with additional 
planes, the bits that represent those planes occupy more significant bits. 


When a plane is to be modified, its corresponding bit in plane_mask 
is set. The default value is all ones, specifying that all planes can be 
modified. 
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DESCRIPTION = SET PLANE MASK changes the value for the plane mask member in the 
GC values data structure. The graphics context identifier was originally 
returned by DEFAULT GC or CREATE GC. 


The plane mask member identifies which planes of a display can be 
modified. There is one bit in the plane mask per plane. The least 
significant bit represents the first plane. As planes are added, they are 
represented by more significant bits. 


You can also change the plane mask with CHANGE GC or SET STATE. 
When you use SET STATE, you must also change the foreground, 
background, and function members. 





X ERRORS 


VAX Cc Description 
X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a defined 
graphics context. 
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SET STATE 


Changes values for the foreground, background, plane mask, and function 
members of a graphics context. 





VAX FORMAT X$SET_STATE 
(display, gc_id, foreground, background, func, 
plane_mask) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns ijongword read reference 
gc_id identifier uns longword read reference 
foreground longword longword read reference 
background longword longword read reference 
func longword iongword read reference 
plane_mask mask_longword uns iongword read reference 





MITC FORMAT XSetState 
(display, gc_id, foreground, background, func, 
plane_mask) 


argument 
information XSetState (display, gc_id, foreground, background, func, 
plane_mask) 
Display *display; 
GC ge_id; 
unsigned long foreground, background; 
int func; 
unsigned long plane_mask; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 
gc_id 
The identifier of the graphics context where the new values will be set. 


The graphics context identifier was originally returned by DEFAULT GC 
or CREATE GC. 
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foreground 

The new value for the foreground member of the graphics context. The 
foreground value is a color index to a color map containing the color 
definition for the foreground. If the value specified is out of range, it is 
truncated to the appropriate number of bits. 


background 

The new value for the background member of the graphics context. The 
background value is a color index to a color map containing the color 
definition for the background. If the value specified is out of range, it is 
truncated to the appropriate number of bits. 


func 
The new value for the function member of the graphics context. 


The function member describes how the new destination bits are computed 
from the source bits and the old destination bits. Table 5-8 lists the valid 
values for func. The default value is 3 for GX Copy. 


Table 5-8 Graphics Context Codes for Function Member 


Hex C Function 

Value VAX Function Name Name Operation 

0 X$C_GX_CLEAR GXclear 0 

4 X$C_GX_AND GXand src AND dst 

2 X$C_GX_AND_REVERSE GXandReverse src AND NOT dst 

3 X$C_GX_COPY GXcopy src 

4 X$C_GX_AND_INVERTED GXandinverted (NOT src) AND dst 

5 X$C_GX_NOOP GXnoop dst 

6 X$C_GX_XOR GXxor src XOR dst 

7 X$C_GX_OR GXor src OR dst 

8 X$C_GX_NOR GXnor (NOT src) AND NOT dst 
9 X$C_GX_EQUIV GXequiv (NOT src) XOR dst 

A X$C_GX_INVERT GXinvert NOT dst 

B X$C_GX_OR_REVERSE GXorReverse src OR NOT dst 

Cc X$C_GX_COPY_INVERTED  GXcopylnverted NOT src 

D X$C_GX_OR_INVERTED GXorlInverted (NOT src) OR dst 

E X$C_GX_NAND GXnand (NOT src) OR NOT dst 
F X$C_GX_SET GXset 1 

plane_mask 


A bit mask that specifies which planes will be modified. 


The plane mask specifies which planes of the display will be modified. For 
monochrome displays, there is only one plane. Within the plane mask, the 
least significant bit represents this plane. For displays with additional 
planes, the bits that represent those planes occupy more significant bits. 
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When a plane is to be modified, its corresponding bit in plane_mask 
is set. The default value is all ones, specifying that all planes can be 
modified. 





DESCRIPTION SET STATE changes values in the GC values data structure for four 
members: 


¢ Foreground 

¢ Background 

¢ Function 

e Planes 

Use the graphics context identifier to refer to the specific graphics context 
that you want to change. 


Use this routine when you want to change all these values in the same 
graphics context. If you want to change individual values, use the routines 
SET FOREGROUND to change the foreground; SET BACKGROUND to 
change the background; SET FUNCTION to change the function value; or 
SET PLANE MASK to change planes. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE __ BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argumeni’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET STIPPLE 


Changes the pixmap identifier of the stipple pattern in the specified graphics 
context. 





VAX FORMAT X$SET_STIPPLE 
(display, gc_id, stipple_id) 





argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
stipple_id identifier longword read reference 





MITC FORMAT XSetStipple 
(display, gc_id, stipple_id) 


argument 

information XSetStipple (display, gc_id, stipple_id) 
Display *display; 
GC gc_id; 


Pixmap stipple_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the pixmap identifier of 
the stipple pattern will be changed. The graphics context identifier was 
originally returned by DEFAULT GC or CREATE GC. 


stipple_id 
The identifier of the pixmap containing the stipple pattern. The pixmap 
identifier was originally returned by CREATE PIXMAP. 





DESCRIPTION _ SET STIPPLE changes the pixmap identifier in the specified graphics 
context to the identifier of a pixmap containing the desired stipple pattern. 
The default value is a pixmap of unspecified size filled with values of 1. 
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The stipple pixmap can be any size, although some sizes might be faster 
to use than others. Use the QUERY BEST STIPPLE routine to determine 
the best size. The stipple pixmap must have the same depth as the 


graphics context. 


You can also use CHANGE GC to specify the pixmap identifier for a stipple 


pattern. 





X ERRORS 


VAX Cc 
X$C_BAD_ALLOC _ BadAlloc 


X$C_BAD_GC BadGC 


X$C_BAD_MATCH  BadMaitch 


X$C_BAD_PIXMAP _ BadPixmap 


Description 


The server did not allocate the requested 
resource for any cause. 


A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


Possible causes are as follows: 


+ Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

¢ An input-only window is used as a 
drawable. 

* One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

« — An input-only window lacks this attribute. 


A value that you specified for a pixmap 
argument does not name a defined pixmap. 
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SET SUBWINDOW MODE 


Changes the value for the subwindow mode in the graphics context. 





VAX FORMAT X$SET_SUBWINDOW_MODE 
(display, gc_id, subwindow_mode) 





argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
subwindow_mode longword longword read reference 





MITC FORMAT XSetSubwindowMode 
(display, gc_id, subwindow_mode) 


argument 

information XSet SubwindowMode (display, gc_id, subwindow_mode) 
Display *display; 
GC gc_id; 


int subwindow_mode; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the subwindow mode member 
will be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


subwindow_mode 
Specifies whether the source and destination windows are clipped by 
subwindows. The predefined values are as follows: 
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VAX Cc Description 

X$C_CLIP_BY_CHILDREN ClipByChildren The source and destination 
windows are clipped. 

X$C_INCLUDE_INFERIORS __Includelnferiors Inferiors clip neither source 


nor destination windows. 
This results in drawing 
through subwindows 
boundaries. 


Other values specified in this argument are not valid. 





DESCRIPTION SET SUBWINDOW MODE changes the value for the subwindow mode in 
the graphics context. 


You can also use CHANGE GC to change the subwindow mode. 





X ERRORS 


VAX Cc Description 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


X$C_BAD_VALUE  BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument’s type is 
accepted. Any argument defined as a set of 
alternatives can generate this error. 
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SET TILE 


Changes the pixmap identifier of the tile pattern in the specified graphics 
context. 





VAX FORMAT X$SET_TILE 
(display, gc_id, tile_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gce_id identifier uns longword read reference 
tile_id identifier uns longword read reference 





MITC FORMAT XSettTile 
(display, gc_id, tile_id) 


argument 

information XSetTile (display, gc_id, tile_id) 
Display *display; 
GC gc_id; 


Pixmap tile_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the tile pixmap identifier will 
be changed. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


tile_id 
The identifier of the pixmap containing the tile pattern. The pixmap 
identifier was originally returned by CREATE PIXMAP. 





DESCRIPTION _ SET TILE changes the pixmap identifier in the specified graphics context 
to the identifier of a pixmap containing the desired tile pattern. The 
default value is a pixmap of unspecified size filled with the foreground 
pixel. 
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SET TILE 


The tile pixmap can be any size, although some sizes might be faster 
to use than others. Use the QUERY BEST TILE to determine the best 
size. The tile pixmap must have the same root and depth as the graphics 


context. 


The graphics context identifier was originally returned by DEFAULT GC 


or CREATE GC. 


You can also use CHANGE GC to specify a tile pixmap identifier. 





X ERRORS 


VAX Cc 
X$C_BAD_ALLOC _BadAlloc 


X$C_BAD_GC BadGC 


X$C_BAD_MATCH BadMatch 


X$C_BAD_PIXMAP _— BadPixmap 


Description 


The server did not allocate the requested 
resource for any cause. 


A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


Possible causes are as follows: 


* Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

* An input-only window is used as a 
drawable. 

« One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

¢ An input-only window lacks this attribute. 


A value that you specified for a pixmap 
argument does not name a defined pixmap. 
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SET TS ORIGIN 


Changes the x- and y-coordinates of the tile or stipple origin in the graphics 
context. 





VAX FORMAT X$SET_TS ORIGIN 
(display, gc_id, ts_x_coord, ts_y_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
gc_id identifier uns longword read reference 
ts_x_coord longword longword read reference 
ts_y_coord longword longword read reference 





MITC FORMAT XSetTSOrigin 
(display, gc_id, ts_x_coord, ts_y_coord) 


argument 

information XSetTSOrigin(display, gc_id, ts_x_ coord, ts_y coord) 
Display *display; 
GC gc_id; 


int ts_x_ coord, ts_y coord; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


gc_id 

The identifier of the graphics context where the tile or stipple origin 
is located. The graphics context identifier was originally returned by 
DEFAULT GC or CREATE GC. 


ts_x_ coord 

The x-coordinate of the tile or stipple origin to be changed. The x- and 
y-coordinates define where the tile or stipple pattern is aligned with the 
origin of the drawable. 


ts_y coord 

The y-coordinate of the tile or stipple origin to be changed. The x- and 
y-coordinates define where the tile or stipple pattern is aligned with the 
origin of the drawable. 


Graphics Context Routines 
SET TS ORIGIN 





DESCRIPTION 


SET TS ORIGIN changes the coordinates of the tile or stipple origin in 
the graphics context. The identifier of the graphics context was originally 
returned by DEFAULT GC or CREATE GC. 


The tile or stipple origin defines the point within the tile or stipple pixmap 
that is aligned with the drawable that will be tiled or stippled. 


When graphics requests call for tiling or stippling, the parent’s origin is 
interpreted to whatever destination drawable is specified in the graphcis 
context. 


You can also change the coordinate values with CHANGE GC. 





X ERRORS 


VAX Cc Description 

X$C_BAD_ALLOC __ BadAlloc The server did not allocate the requested 
resource for any cause. 

X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a defined 
graphics context. 
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Use the graphics routines to complete the following graphics operations: 


Clearing areas 

Copying areas 

Drawing points 

Drawing lines 

Drawing rectangles 

Drawing arcs 

Filling rectangles, polygons, and arcs 


Creating and manipulating images 


For concepts related to graphics routines and information on how to use 
graphics routines, see the VMS DECwindows Xlib Programming Volume. 


The routines described in this chapter are listed in Table 6-1. 


Table 6-1 Graphics Routines 


Routine Name Description 

ADD PIXEL Increments each pixel in a pixmap by a constant value. 

CLEAR AREA Clears a rectangular area in a window. 

CLEAR WINDOW Clears an entire window. 

COPY AREA Copies a specified rectangular area from one window or 
pixmap (drawable) to another drawable. 

COPY PLANE Copies a rectangular area from one plane of a window or 
pixmap (drawable) to another drawable. 

CREATE IMAGE Specifies the size of the image and allocates sufficient 
memory for the image data structure. 

DRAW ARC Draws one arc in the specified window or pixmap. 

DRAW ARCS Draws more than one arc in the specified window or 
pixmap. 

DRAW LINE Draws one line between two points in the specified window 
or pixmap. 

DRAW LINES Draws more than one connected line in the specified 
drawable. 

DRAW POINT Draws a point in the specified window or pixmap. 

DRAW POINTS Draws more than one point in the specified drawable. 





(continued on next page) 
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Table 6-1 (Cont.) Graphics Routines 


Routine Name 


Description 





DRAW RECTANGLE 


DRAW RECTANGLES 


DRAW SEGMENTS 


FILL ARC 


FILL ARCS 


FILL POLYGON 
FILL RECTANGLE 


FILL RECTANGLES 


GET IMAGE 


GET PIXEL 
PUT IMAGE 


PUT PIXEL 


SUBIMAGE 


Draws the outline of one rectangle in the specified drawable. 


Draws the outline of more than one rectangle in the 
specified drawable. 


Draws more than one line in the specified drawable. The 
lines are not connected. 


Fills in either a pie slice or chord area of an arc in the 
specified drawable. 


Fills in either a pie slice or a chord area of more than one 
arc in the specified window or pixmap. 


Fills a polygon area in a specified drawable. 


Fills the area defined by a rectangular outline in the 
specified drawable. 


Fills the areas defined by rectangular outlines in the 
specified drawable. 


Returns the contents of a rectangle to the specified 
drawable. 


Obtains the value of one pixel stored in an image. 


Combines the image in memory with the image in a 
specified rectangle on the specified drawable. 


Changes one pixel value within the pixmap containing an 
image. 


Creates a new image from an existing image. 


The graphics routines use several predefined data structures for points, 
unconnected line segments, rectangles, and arcs. 


Point Data Structure 





The point data structure defines a list of coordinates for use with the 
DRAW POINTS and DRAW LINES routines. In the case of DRAW 
POINTS, it affects those pixels of the specified coordinates, while in 
the case of DRAW LINES, it uses the specified coordinates as endpoints 
of consecutive, adjoining lines. The data structure for the VAX binding 
is shown in Figure 6—1, and information about members in the data 
structure is described in Table 6-2. 


Figure 6-1 Point Data Structure (VAX Binding) 
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Table 6-2 Members of the Point Data Structure (VAX Binding) 





Member Name Contents 
X$W_GPNT_X Defines the x value of the coordinate of a point 
X$W_GPNT_Y Defines the y value of the coordinate of a point 


The data structure for the MIT C binding is shown in Figure 6-2, 
and information about members in the data structure is described in 
Table 6-3. 


Figure 6~2 Point Data Structure (MIT C Binding) 


typedef struct { 
short x,y? 
}XPoint; 


Table 6-3 Members of the Point Data Structure (MIT C Binding) 


Member Name Contents 
Xx Defines the x value of the coordinate of a point 
y Defines the y value of the coordinate of a point 





Segment Data Structure 


The segment data structure defines the x- and y-coordinates for two points. 
A line segment is drawn between one pair of points. The data structure 
for the VAX binding is shown in Figure 6-3. 


Figure 6-3 Segment Data Structure (VAX Binding) 






x$w_gseg_y1 x$w_gseg_x1 
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6.2 Segment Data Structure 


The MIT C binding segment data structure is shown in Figure 6—4. 
Figure 6-4 Segment Data Structure (MIT C Binding) 
typedef struct { 


short x1,y1,x2,y2; 
} XSegment; 





Rectangle Data Structure 


The rectangle data structure defines the upper left corner and the width 
and height of a rectangle. The data structure for the VAX binding is shown 
in Figure 6-5, and information about members in the data structure is 
described in Table 6-4. 


Figure 6-5 Rectangle Data Structure (VAX Binding) 











x$w_grec_height x$w_grec_width 





Table 6-4 Members of the Rectangle Data Structure (VAX Binding) 


Member Name Contents 

X$W_GREC_X Defines the x value of the rectangle origin 
X$W_GREC_Y Defines the y value of the rectangle origin 
X$W_GREC_WIDTH Defines the width of the rectangle 
X$W_GREC_HEIGHT Defines the height of the rectangle 


The data structure for the MIT C binding is shown in Figure 6-6, 
and information about members in the data structure is described in 
Table 6—5. 


Graphics Routines 
6.3 Rectangle Data Structure 


Figure 6-6 Rectangle Data Structure (MIT C Binding) 





typedef struct { 

short x,y? 

unsigned short width, height; 
} XRectangle; 





Table 6—~5 Members of the Rectangle Data Structure (MIT C Binding) 








Member Name Contents 

Xx Defines the x value of the rectangle origin 
y Defines the y value of the rectangle origin 
width Defines the width of the rectangle 

height Defines the height of the rectangle 





Arc Data Structure 


The arc data structure defines the starting point and size of an arc. 
The data structure for the VAX binding is shown in Figure 6—7, and 
information about members in the data structure is described in 
Table 6-6. 


Figure 6-7 Arc Data Structure (VAX Binding) 


: 
x$w_garc_height x$w_garc_width 4 
x$w_garc_angle2 x$w_garc_angle1 8 





Table 6-6 Members of the Arc Data Structure (VAX Binding) 


Member Name Contents 

X$W_GARC_X Defines the x-coordinate value of the rectangle in which 
the server draws the arc 

X$W_GARC_Y Defines the y-coordinate value of the rectangle in which 
the server draws the arc 

X$W_GARC_WIDTH Defines the x axis diameter of the arc 
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Table 6—6 (Cont.} Members of the Arc Data Structure (VAX Binding) 


Member Name Contents 

X$W_GARC_HEIGHT Defines the y axis diameter of the arc 

X$W_GARC_ANGLE1 Defines the starting point of the arc relative to the three 
o’clock position from the center of the rectangle 

X$W_GARC_ANGLE2 Defines the extent of the arc relative to the starting point 


The data structure for the MIT C binding is shown in Figure 6-8, 
and information about members in the data structure is described in 
Table 6—7. 


Figure 6-8 Arc Data Structure (MIT C Binding) 


typedef struct { 
short x,y; 
unsigned short width, height; 
short anglel, angle2; 

} XArc; 


Table 6-7 Members of the Arc Data Structure (MIT C Binding) 


Member Name Contents 





Xx Defines the x-coordinate of the rectangle in which the server 
draws the arc 

y Defines the y-coordinate of the rectangle in which the server 
draws the arc 

width Defines the x axis diameter of the arc 

height Defines the y axis diameter of the arc 

angle Defines the starting point of the arc relative to the three o'clock 
position from the center of the rectangle 

angle2 Defines the extent of the arc relative to the starting point 

6.5 Image Data Structure 


Each image is defined and referenced using the image data structure. 
The data structure for the VAX binding is shown in Figure 6—9, and 
information about members in the data structure is described in Table 6-8. 
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Figure 6-9 Image Data Structure (VAX Binding) 

























; 
x$l_imag_format 12 

: 
x$l_imag_byte_order 20 

. 
x$l_imag_bitmap_bit_order 28 
: 
: 
: 
x$l_imag_bits_per_pixel 44 

: 
: 
: 
: 
x$a_imag_create_image 64 

: 
x$a_imag_get_pixel 72 

: 
x$a_imag_sub_image 80 

; 
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Table 6-8 Members of the Image Data Structure (VAX Binding) 





Member Name 


X$L_IMAG_WIDTH 
X$L_IMAG_HEIGHT 
X$L_IMAG_OFFSET 


X$L_IMAG_FORMAT 


X$A_IMAG_DATA 
X$L_IMAG_BYTE_ORDER 
X$L_IMAG_BITMAP_UNIT 
X$L_IMAG_BITMAP_BIT_ORDER 
X$L_IMAG_BITMAP_PAD 


X$L_IMAG_DEPTH 
X$L_IMAG_BYTES_PER_LINE 
X$L_IMAG_BITS_PER_PIXEL 
X$L_IMAG_RED_MASK 
X$L_IMAG_GREEN_MASK 
X$L_IMAG_BLUE_MASK 
X$A_IMAG_OBDATA 
X$A_IMAG_CREATE_IMAGE 
X$A_IMAG_DESTROY_IMAGE 
X$A_IMAG_GET_PIXEL 
X$A_IMAG_PUT_PIXEL 
X$A_IMAG_SUB_IMAGE 
X$A_IMAG_ADD_PIXEL 


Contents 


Specifies the width of the image 
Specifies the height of the image 


Specifies the number of pixels offset in the x direction. Specifying an offset 
permits the server to ignore the beginning of scan lines and rapidly display 
images when ZPixmap format is used. 


Specifies whether the data is stored in XYPixmap or ZPixmap format. The 
following flags facilitate specifying data format: 





Flag Name Description 


x$c_xy_bitmap 
x$c_xy_pixmap 
x$c_z_pixmap 


A single bitmap representing one plane 
A set of bitmaps representing individual planes 


Data organized as a list of pixel values viewed as 
a horizontal row 


The address of the image data 

Indicates whether the least significant or the most significant byte is first 
Specifies whether the bitmap is organized in units of 8, 16, or 32 bits 
Specifies whether the bitmap order is least or most signficant 


Specifies whether padding in XY format or Z format should be done in 
units of 8, 16, or 32 bits 


The depth of the image 

The bytes per line to be used as an accelerator 
Indicates for Z format the number of bits per pixel 
Specifies the red values for ZFormat 

Specifies the green values for ZFormat 
Specifies the blue values for ZFormat 

A structure that contains object routines 

A CREATE IMAGE routine 

A DESTROY IMAGE routine 

A GET PIXEL routine 

A PUT IMAGE routine 

A SUB IMAGE routine 

An ADD PIXEL routine 





The data structure for the MIT C binding is shown in Figure 6-10, 
and information about members in the data structure is described in 


Table 6-9. 


Figure 6-10 
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Image Data Structure (MIT C Binding) 


typedef struct_XImage{ 


}XImage; 


int 
int 
int 


width, height; 
xoffset; 
format; 


char *data; 


int 
int 
int 
int 
int 
int 
int 
uns 
uns 
uns 


byte order; 

bitmap _unit; 

bitmap _bit_order; 
bitmap pad; 

depth; 
bytes _per line; 
bits_per pixel; 

igned long red_mask; 
igned long green_mask; 
igned long blue_mask; 


char *obdata; 
struct funcs { 


}£; 


struct_XImage *(*create_image) (); 
int (*destroy image) (); 

unsigned long (*get_pixel) (); 

int (*put_pixel) (); 

struct_Ximage* (*sub_image) (); 

int (*add_pixel) (); 


Table 6-9 Members of the Image Data Structure (MIT C Binding) 


Member Name Contents 
width Specifies the width of the image in pixels. 
height Specifies the height of the image in pixels. 
offset Specifies the number of bits offset in the x direction. 
Specifying an offset permits the server to ignore the 
beginning of scan lines and rapidly display images when 
ZPixmap format is used. 
format Specifies whether the data is stored in XYPixmap or 
ZPixmap format. The following flags facilitate specifying 
data format: 
Constant 
Name Description 
XYBitmap A single bitmap representing one plane 
XYPixmap A set of bitmaps representing individual 
planes 
ZPixmap Data organized as a list of pixel values 
viewed as a horizontal row 
data The address of the image data. 


(continued on next page) 
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Table 6-9 (Cont.) 


Member Name 


byte_order 


bitmap_unit 


bitmap_bit_order 


bitmap_pad 


depth 
bytes_per_line 
bits_per_pixel 
red_mask 
green_mask 
blue_mask 
obdata 
create_image 
destroy_image 
get_pixel 
put_pixel 
sub_image 
add_pixel 


Members of the Image Data Structure (MIT C Binding) 


Contents 


Indicates whether the least significant or the most significant 
byte is first. The following flags facilitate specifying byte 
order: 


Constant 

Name Description 

LSBFirst Least significant byte first 
MSBFirst Most significant byte first 


Specifies whether the bitmap is organized in units of 8, 16, 
or 32 bits (not used with ZPixmap). 


Specifies whether the least significant or most significant bit 
is first. The following flags facilitate specifying bitmap order: 


Constant 

Name Description 

LSBFirst Least significant byte first 
MSBFirst Most significant byte first 


Specifies whether scan line padding in XY format or Z 
format should be done in units of 8, 16, or 32 bits. 


Specifies the depth of the image. 

Specifies the bytes per line to be used as an accelerator. 
Indicates for ZFormat the number of bits per pixel. 
Specifies red values for ZFormat. 

Specifies green values for ZFormat. 

Specifies blue values for ZFormat. 

The address of a structure that contains object routines. 
The address of a CREATE IMAGE routine. 

The address of a DESTROY IMAGE routine. 

The address of a GET PIXEL routine. 

The address of a PUT PIXEL routine. 

The address of a SUB IMAGE routine. 

The address of an ADD PIXEL routine. 





6.6 Graphics Routines 


The following pages describe the Xlib graphics routines. 
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ADD PIXEL 
Increments each pixel in an image by a constant value. 
VAX FORMAT X$ADD_PIXEL (ximage, value) 
argument 
information Argument Usage Data Type Access Mechanism 
ximage record x$image read reference 
value longword longword read reference 





MITC FORMAT XAddPixel (ximage, value) 


argument 

information int XAddPixel (ximage, value) 
XImage *ximage; 
int value; 





ARGUMENTS '-  Ximage 


The image data structure which contains the image to be changed. For 
more information on the image data structure, see Section 6.5. 


value 


The constant value to add to each pixel. 





DESCRIPTION ADD PIXEL adds a constant value to each pixel in an image. 
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CLEAR AREA 


Clears a rectangular area in a window. 





VAX FORMAT X$CLEAR_AREA 
(display, window_id, x_coord, y_coord, width, height, 


exposures) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 
exposures Boolean uns longword read reference 





MITC FORMAT XClearArea 
(display, window_id, x_coord, y_coord, width, height, 


exposures) 
argument 
information XClearArea (display, window_id, x_coord, y_ coord, width, height, 
exposures) 


Display *display; 

Window window_id; 

int x_coord, y coord; 
unsigned int width, height; 
Bool exposures; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window _id 
The identifier of the window where an area will be cleared. If the window 
specified is an input-only window, an error will occur. 


x_coord 

The x-coordinate of the rectangle to be cleared. This coordinate is relative 
to the origin of the window. The x- and y-coordinates define the upper left 
corner of the rectangle. 
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y_coord 

The y-coordinate of the rectangle to be cleared. This coordinate is relative 
to the origin of the window. The x- and y-coordinates define the upper left 
corner of the rectangle. 


width 
The width, in pixels, of the rectangle to be cleared. The width and height 
determine the area of the rectangle to be cleared. 


If the value of width is zero, it is assigned a default value equivalent to 
the current width of the window minus the value of the x-coordinate. 


height 
The height, in pixels, of the rectangle to be cleared. The width and height 
determine the area of the rectangle to be cleared. 


If the value of height is zero, it is assigned a default value equivalent to 
the current height of the window minus the value of the y-coordinate. 


exposures 

The flag that specifies whether or not one or more exposure events are 
generated. When true, one or more exposure events are generated for 
regions of the rectangle that are either visible or are being retained in a 
backing store. When false, no exposure events are generated. 





DESCRIPTION 


CLEAR AREA clears a rectangular area in a specified window. 


The rectangle is defined by the arguments x_coord, y_coord, width, and 
height and by the window origin coordinates. The x- and y-coordinates 
are relative to the window origin coordinates and define the upper left 
corner of the rectangle. The width and height specify the area. For 
example, if you specify the width and height to be 10 and 10, the rectangle 
to be cleared would be as shown in Figure 6-11. 
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Figure 6-11 Rectangular Area Cleared 


Drawable Origin (10,10) 





(20,20) 


Height (10) 


Width (10) 
ZK-0015A-GE 


The area cleared is replaced by a background. If the background has a 
specific tile pattern, the rectangular area is tiled with a plane mask of all 
ones and a function of GXcopy. If the background is none, the contents of 
the cleared rectangular area do not change. 


To clear the entire window, use CLEAR WINDOW. 





X ERRORS 
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X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

* An input-only window is used as a 
drawable. 

*« One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

* — An input-only window lacks this attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, 
the full range defined by the argument’s type 
is accepted. Any argument defined as a set 
of alternatives can generate this error. 


X$C_BAD_ BadWindow A value that you specified for a window 
WINDOW argument does not name a defined window. 
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CLEAR WINDOW 


Clears an entire window. 





VAX FORMAT X$CLEAR_WINDOW (display, window_id) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
window_id identifier uns longword read reference 





MITC FORMAT XClearWindow (display, window_id) 


argument 

information XClearWindow (display, window_id) 
Display *display; 
Window window_id; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


window_id 
The identifier of the window to be cleared. 





DESCRIPTION CLEAR WINDOW clears the entire window area. The identifier of the 
window was originally returned by CREATE SIMPLE WINDOW or 
CREATE WINDOW. 


The area cleared is replaced by the window’s background. If the 
background has a defined tile, the window is tiled with a plane mask of all 
ones and a function of GXcopy. If the background is none, the contents of 
the cleared window does not change. 


To clear an area within a window, use CLEAR AREA. 
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X ERRORS 


VAX Cc Description 





X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

* An input-only window is used as a 
drawable. 

« One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

* — An input-only window lacks this attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, 
the full range defined by the argument’s type 
is accepted. Any argument defined as a set 
of alternatives can generate this error. 


X$C_BAD_ BadWindow A value that you specified for a window 
WINDOW argument does not name a defined window. 
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COPY AREA 


Copies a specified rectangular area from one window or pixmap (drawable) to 
another drawable. 





VAX FORMAT xX$COPY_AREA 
(display, src_drawable_id, dst_drawable_id, gc_id, 
src_x_coord, src_y_coord, width, height, dst_x_coord, 
dst_y_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
src_drawable_id _ identifier uns longword read reference 
dst_drawable_id identifier uns longword read reference 
ge_id identifier uns longword read reference 
src_x_coord longword longword read reference 
src_y_coord longword longword read reference 
width longword uns longword read reference 
height fongword uns longword read reference 
dst_x_coord longword longword read reference 
dst_y_coord longword longword read reference 





MITC FORMAT XCopyArea 
(display, src_drawable_id, dst_drawable_id, gc_id, 
src_x_coord, src_y_coord, width, height, dst_x_coord, 
dst_y_coord) 


argument 
information XCopyArea (display, src_drawable_id, dst_drawable_id, gc_id, 
src_x_ coord, src_y coord, width, height, dst_x coord, 
dst_y coord) 
Display *display; 
Drawable src_drawable_id, dst_drawable_id; 
GC gc_id; 
int sre_x_ coord, sre_y coord; 
unsigned int width, height; 
int dst_x_ coord, dst_y coord; 
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ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


src_drawable_id 

The identifier of the source window or pixmap (drawable) containing the 
rectangular area to be copied. The drawable identifier can be either a 
window or pixmap identifier. The source drawable must be of the same 
root and depth as the destination drawable. 


dst_drawable_id 

The identifier of the destination window or pixmap (drawable) where the 
rectangular area will be copied to. The drawable identifier can be either 
a window or pixmap identifier. The destination drawable must be of the 
same root and depth as the source drawable. 


gc_id 
The identifier of the graphics context associated with the drawables. 


src_x_coord 

The x-coordinate of the rectangle to be copied from the source drawable. 
The x-coordinate is relative to the origin of the drawable. The x- and 
y-coordinates define the upper left corner of the rectangle. 


src_y_coord 

The y-coordinate of the rectangle to be copied from the source drawable. 
The y-coordinate is relative to the origin of the drawable. The x- and 
y-coordinates define the upper left corner of the rectangle. 


width 

The width, in pixels, of the rectangle. The width and height define the 
area of the rectangle to be copied. The rectangle copied to the destination 
drawable also has the same dimensions. 


height 

The height, in pixels, of the rectangle. The width and height define the 
area of the rectangle to be copied. The rectangle copied to the destination 
drawable also has the same dimensions. 


dst_x_coord 

The x-coordinate of the destination drawable where the rectangle will be 
copied to. The x-coordinate is relative to the origin of the drawable. The 
x- and y-coordinates define the upper left corner of the rectangle. 


dst_y coord 

The y-coordinate of the destination drawable where the rectangle will be 
copied to. The y-coordinate is relative to the origin of the drawable. The 
x- and y-coordinates define the upper left corner of the rectangle. 





DESCRIPTION 
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COPY AREA copies a rectangular area from one window or pixmap 
drawable) to another drawable. The drawables are specified by their 
identifiers. If the drawables are pixmaps, the identifiers were originally 
returned by CREATE PIXMAP. If the drawables are windows, the 
identifiers were originally returned by any CREATE WINDOW request. 


Graphics Routines 
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The rectangular area to be copied is specified as follows: 


¢ The starting point is specified by x- and y-coordinates in sre_x_coord 
and sre_y_coord. These coordinates define the upper left corner of 
the rectangle, in relation to the origin of the drawable. 


¢ The size of the rectangle is specified by width and height. 


The rectangular area copied is specified as follows: 


¢ The place where the copying starts is specified by x- and y-coordinates 
in dst_x_coord and dst_y_coord. These coordinates define the upper 
left corner of the rectangle, in relation to the origin of the drawable. 


e The size of the rectangle is defined by width and height. 

COPY AREA uses the graphics context to define how copying is done. The 
following members are used: 

* Function 

¢ Plane Mask 

¢ Subwindow Mode 

¢ Graphics Exposures 

¢ Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 

COPY AREA combines the specified rectangle from the source with the 
specified rectangle of the destination. If the regions of the source rectangle 
are obscured and have not been retained by the server, or if regions outside 
the boundaries of the source drawable are specified, the corresponding 
regions of the destination are tiled with the plane mask member of all 


ones and function GXcopy with that background, unless the destination 
drawable is a window with a background of none. 


When the graphics exposure member in the graphics context is true, 
graphics exposure events for the corresponding destination regions are 
generated. If the graphics exposure member is true, but no regions are 
exposed, then a no expose event is generated. 





X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


6-19 


Graphics Routines 


COPY AREA 


6-20 


VAX Cc Description 


X$C_BAD_ MATCH BadMatch Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 


COPY PLANE 
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Copies a rectangular area from one plane of a window or pixmap (drawable) 
to another drawable. 





VAX FORMAT xX$COPY_PLANE 
(display, src_drawable_id, dst_drawable_id, gc_id, 

src_x_coord, src_y_coord, width, height, dst_x_coord, 
dst_y_coord, plane) 


argument 
information 


Argument 


display 
src_drawable_id 
dst_drawable_id 
gc_id 
src_x_coord 
src_y_coord 
width 

height 
dst_x_coord 
dst_y_coord 
plane 


Usage 
identifier 
identifier 
identifier 
identifier 
longword 
longword 
longword 
longword 
longword 
longword 
mask_longword 


Data Type 


uns longword 
uns longword 
uns longword 
uns longword 
iongword 
longword 
uns longword 
uns longword 
longword 
longword 
uns longword 


Access 


read 
read 
read 
read 
read 
read 
read 
read 
read 
read 
read 


Mechanism 


reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 
reference 





MIT C FORMAT XCopyPlane 
(display, src_drawable_id, dst_drawable_id, gc_id, 

src_x_coord, src_y_coord, wiath, height, dst_x_coord, 
dst_y_coord, plane) 


argument 
information 


XCopyPlane(display, src_drawable_id, dst_drawable_id, gc_id, 
src_x coord, src_y coord, width, height, dst_x coord, 


dst_y_coord, plane) 


Display *display; : 
Drawable src_drawable_id, dst_drawable_id; 
GC gc_id; 
int src_x_ coord, src_y coord; 
unsigned int width, height; 

int dst_x coord, dst_y coord; 
unsigned long plane; 
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display 
The display information originally returned by OPEN DISPLAY. 


src_drawable_id 

The identifier of the window or pixmap (drawable) containing the bit 
plane to be copied. The drawable identifier can be either a window or 
pixmap identifier. The source drawable must be of the same root, but not 
necessarily of the same depth, as the destination drawable. 


dst_drawable_id 

The identifier of the window or pixmap (drawable) where the bit plane will 
be copied to. The drawable identifier can be either a window or pixmap 
identifier. The destination drawable must be of the same root, but not 
necessarily of the same depth, as the source drawable. 


gc_id 


The identifier of the graphics context associated with the drawables. 


src_x_coord 

The x-coordinate of the rectangle to be copied from the plane of the source 
drawable. The x-coordinate is relative to the origin of the drawable. The 
x- and y-coordinates define the upper left corner of the rectangle. 


src_y coord 

The y-coordinate of the rectangle to be copied from the plane of the source 
drawable. The y-coordinate is relative to the origin of the drawable. The 
x- and y-coordinates define the upper left corner of the rectangle. 


width 

The width, in pixels, of the rectangle. The width and height define the 
area of the rectangle to be copied. The rectangle copied to the destination 
drawable also has the same dimensions. 


height 

The height, in pixels, of the rectangle. The width and height define the 
area of the rectangle to be copied. The rectangle copied to the destination 
drawable also has the same dimensions. 


dst_x_coord 

The x-coordinate within a plane of the destination drawable where the 
rectangle will be copied to. The x-coordinate is relative to the origin of 
the drawable. The x- and y-coordinates define the upper left corner of the 
rectangle. 


dst_y_coord 

The y-coordinate within a plane of the destination drawable where the 
rectangle will be copied to. The y-coordinate is relative to the origin of 
the drawable. The x- and y-coordinates define the upper left corner of the 
rectangle. 


plane 

A bit mask that specifies which plane to copy from. Exactly one bit is 
set to 1. The least significant bit represents the first plane; increasingly 
significant bits represent subsequent planes (in order). 
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DESCRIPTION 


COPY PLANE copies a rectangular area from a plane of a window or 
pixmap (drawable) to another drawable. The drawables are specified 

by their identifiers. If the drawables are pixmaps, the identifiers were 
originally returned by CREATE PIXMAP. If the drawables are windows, 
the identifiers were originally returned by CREATE SIMPLE WINDOW or 
CREATE WINDOW. 


The rectangular area to be copied is specified as follows: 


¢ The starting point is specified by x- and y-coordinates in sre_x_coord 
and sre_y_coord. These coordinates define the upper left corner of 
the rectangle, in relation to the origin of the drawable. 


¢ The size of the rectangle is defined by width and height. 


The rectangular area copied is specified as follows: 


¢ The place where the copying starts is specified by x- and y-coordinates 
in dst_x_coord and dst_y_coord. These coordinates define the upper 
left corner of the rectangle, in relation to the origin of the drawable. 


¢ The size of the rectangle is defined by width and height. 
COPY PLANE uses the graphics context to define how copying is done. 
The following members are used: 

¢ Function 

¢ Plane Mask 

e Foreground 

¢ Background 

¢ Subwindow Mode 

* Graphics Exposures 

* Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 


For more information about the graphics context data structure and each 
of its members, see Section 5.1. 


COPY PLANE combines the rectangular area of the plane from the source 
drawable with the foreground/background pixels in the graphics context 
to form a pixmap of the same depth as the destination drawable. The 
rectangular area of the plane is treated similarly to an opaque stippled fill. 
All ones are replaced by the foreground color, and all zeros are replaced by 
the background color. The equivalent of a call to COPY AREA is performed 
with all the same exposure semantics. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An inputonly window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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CREATE IMAGE 


Specifies the size of the image and allocates sufficient memory for the image 
data structure. 





VAX FORMAT 


argument 
information 


status_return = X$CREATE_IMAGE 
(display, visual_id, depth, image_format, offset, 
data, width, height, bitmap_pad, bytes_per_line, 
ximage_return) 


Argument Usage Data Type Access Mechanism 


status_return longword longword write value 

display identifier uns longword read reference 
visual_id identifier uns longword read reference 
depth longword longword read reference 
image_format longword longword read reference 
offset longword longword read reference 
data char string char string read descriptor 
width longword uns longword read reference 
height longward uns longword read reference 
bitmap_pad longword longword read reference 
bytes_per_line longword longword read reference 
ximage_return record x$image write reference 





MITC FORMAT ximage_return = XCreatelmage 


(display, visual_id, depth, image_format, offset, data, 
width, height, bitmap_pad, bytes_per_line) 
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argument 
information 


XImage *XCreateImage (display, visual_id, depth, image_format, 
offset, data, width, height, bitmap_pad, 
bytes per line) 

Display *display; 
Visual *visual_id; 
unsigned int depth; 
int image format; 
int offset; 

char *data; 

unsigned int width; 
unsigned int height; 
int bitmap_pad; 

int bytes_per_line; 





RETURNS 


status_return (VAX only) 


Specifies whether or not the return completed successfully. 


ximage_return (MIT C only) 


A pointer to the newly created image. 





ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


visual_id 

A pointer to a visual structure. For information about this visual 
structure, see the description of the DEFAULT VISUAL routine in 
Chapter 2. 


depth 
The depth of the image that will be created and referenced by the image 
data structure. 


image_format 
The format of the image that will be created and referenced by the image 
data structure. The predefined values for format are as follows: 


VAX Cc 

X$C_BITMAP Bitmap Bitmap image 
X$C_XY_PIXMAP XYPixmap XY pixmap format image 
X$C_Z_PIXMAP ZPixmap Z pixmap format image 


Other values specified in this argument are not valid. 


offset 


The number of pixels beyond the first address of a scan line where an 
image actually begins. The offset argument is useful when the image is 
not on an addressable boundary. 


data 
A pointer to the data that defines the image. 
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width 


The width, in pixels, of the image. The width and height determine the 
area of the image. 


height 
The height, in pixels, of the image. The width and height determine the 
area of the image. 


bitmap_pad 

The space allocated in memory for each scan line. This value specifies the 
number of bits to multiply by bytes_per_line. The value of the 
bitmap_pad argument must be 8, 16, or 32. 


bytes_per_line 

The number of bytes in a scan line. When zero, it is assumed that the 
scan lines are contiguous in memory and the number of bytes per line will 
then be calculated for you. 


ximage_return 
A pointer to the newly created image. 





DESCRIPTION 


CREATE IMAGE allocates memory for the image data structure. It 
initializes the image data structure with the values you specify in the 
arguments. A pointer to the image data structure is returned. Use this 
pointer in subsequent routines to reference the image data structure. 


CREATE IMAGE does not allocate space for the image itself. 


The red, green, and blue mask values stored in the image data structure 
are relevant only for z pixmap format images. If you are working with the 
Z pixmap format, these values are derived from the visual type specified in 
visual_id. 





X ERRORS 


VAX Cc Description 

X$C_BAD_ALLOC BadAlloc The server did not allocate the requested 
resource for any cause. 

X$C_BAD_COLOR BadColor A value that you specified for a color map 
argument does not name a defined color 
map. 

X$C_BAD_ BadCursor A value that you specified for a cursor 

CURSOR argument does not name a defined cursor. 
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VAX Cc 


X$C_BAD_MATCH BadMatch 


X$C_BAD_PIXMAP — BadPixmap 


X$C_BAD_VALUE — BadValue 


X$C_BAD_ BadWindow 
WINDOW 


Description 


Possible causes are as follows: 


¢ In agraphics request, the root and depth 
of the graphics context do not match 
those of the drawable. 

« — An input-only window is used as a 
drawable. 

* One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by 
the request. 

* — An input-only window lacks this attribute. 


A value that you specified for a pixmap 
argument does not name a defined pixmap. 


Some numeric values fall outside the range 
of values accepted by the request. Unless a 
specific range is specified for an argument, 
the full range defined by the argument’s type 
is accepted. Any argument defined as a set 
of alternatives can generate this error. 


A value that you specified for a window 
argument does not name a defined window. 
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DESTROY IMAGE 


Deallocates the memory associated with an image structure. 





VAX FORMAT _ status_return = X$DESTROY_IMAGE  (ximage) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
ximage record x$image read reference 





MIT C FORMAT _siatus_return=XDestroylmage (ximage) 


argument 


information int *XDestroyImage (ximage) 
XImage *ximage; 


RETURNS status_return 


A return value that specifies whether or not the routine completed 
successfully. 





ARGUMENTS  ximage 


A pointer to the image data structure that you want to destroy. 





DESCRIPTION DESTROY IMAGE deallocates the memory associated with an image data 
structure. 


When the image specified by ximage was created by CREATE IMAGE, 
GET IMAGE, or SUB IMAGE, the destroy procedure that DESTROY 
IMAGE calls frees both the image structure and the data pointed to by the 
image structure. 
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DRAW ARC 


Draws one arc in the specified window or pixmap. 





VAX FORMAT X$DRAW_ARC 
(display, drawable_id, gc_id, x_coord, y_coord, width, 
height, angle1, angle2) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 
angle longword longword read reference 
angle2 longword longword read reference 





MITC FORMAT XDrawArc 
(display, drawable_id, gc_id, x_coord, y_coord, width, 
height, angle1, angle2) 


argument 
information XDrawAre (display, drawable_id, gc_id, x_coord, y coord, width, 
height, anglel, angle2) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x_coord, y_coord; 
unsigned int width, height; 
int anglel, angle2; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) to draw the arc in. The 
drawable identifier can be either a window or pixmap identifier. If the 
drawable is a window, the identifier was originally returned by CREATE 
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SIMPLE WINDOW or CREATE WINDOW. If the drawable is a pixmap, 
the identifier was originally returned by CREATE PIXMAP. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


x_coord 

The x-coordinate of the rectangle used to define the arc. This coordinate is 
relative to the origin of the drawable. The x- and y-coordinates define the 
upper left corner of the rectangle. 


y_coord 

The y-coordinate of the rectangle used to define the arc. This coordinate is 
relative to the origin of the drawable. The x- and y-coordinates define the 
upper left corner of the rectangle. 


width 

The width, in pixels, of the rectangle used to define the arc. The width 
and height are the major and minor axes of the arc. If one of the axes is 
specified as zero, a horizontal or vertical line is drawn. 


height 

The height, in pixels, of the rectangle used to define the arc. The width 
and height are the major and minor axes of the arc. If one of the axes is 
specified as zero, a horizontal or vertical line is drawn. 


anglet 

The angle to specify the beginning of the arc relative to the three o’clock 
position from the center. This value is in degrees, scaled by 64 with 
positive indicating counterclockwise motion and negative indicating 
clockwise motion. 


angle2 

The angle to specify the path and extent of the arc relative to the start 
of the arc. This value is in degrees, scaled by 64 with positive indicating 
counterclockwise motion and negative indicating clockwise motion. 





DESCRIPTION DRAW ARC draws one arc in the specified drawable. To specify the 
dimensions of an arc, follow this procedure: 


° Specify a rectangle that represents the size of the ideal center path of 
an ellipse from which the arc will be cut. The x_coord and y_coord 
arguments specify the upper left corner of the rectangle. The width 
and height arguments specify the size of the rectangle. 


* Specify where the arc should start in relation to the three o’clock 
position within the ellipse (in anglel). 


* Specify the extent or angular length of the arc, relative to the start of 
the arc (in angle2). 
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Figure 6-12 illustrates the angles that specify an ellipse. 


Figure 6-12 Specifying an Arc 
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DRAW ARC uses the following graphics context members: 


Function 

Plane Mask 
Subwindow Mode 
Graphics Exposures 
Clip X Origin 

Clip Y Origin 

Clip Mask 


DRAW ARC also uses the following mode-dependent members: 


Foreground 
Background 
Tile 

Stipple 

Ts x origin 
Ts y origin 
Dash offset 
Dash list 
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For more information about the graphics context data structure and each 
of its members, see Section 5.1. 


When you want to draw more than one arc, use DRAW ARCS. Using 
DRAW ARC repeatedly is less efficient than using DRAW ARCS. 


For information about filling an arc, see the descriptions of the FILL ARC 
and FILL ARCS routines. 





X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« An input-only window is used as a 
drawable. 

+ One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 


6-33 


Graphics Routines 


DRAW ARCS 


DRAW ARCS 


Draws more than one arc in the specified window or pixmap. 





VAX FORMAT 


argument 
information 


X$DRAW_ARCS 
(display, drawable_id, gc_id, arcs, num_arcs) 


Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
arcs array x$arc read reference 
num_arcs longword longword read reference 





MITC FORMAT XDrawArcs 


argument 
information 


(display, drawable_id, gc_id, arcs, num_arcs) 


XDrawArcs (display, drawable_id, gc_id, arcs, num_arcs) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
XArc *arcs; 
int num_arcs; 





ARGUMENTS 
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display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) to draw the arcs in. 
The drawable identifier can be either a window or pixmap identifier. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


arcs 
A pointer to an array of arc data structures, where each element defines 
one arc to be drawn. The length of the array is specified by num_ares. 
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num_arcs 
The number of arcs to be drawn. This value specifies the length of the 
array arcs. 





DESCRIPTION 


DRAW ARCS draws more than one arc in the specified drawable. If the 
drawable is a window, the identifier was originally returned by CREATE 
SIMPLE WINDOW or CREATE WINDOW. If the drawable is a pixmap, 
the identifier was originally returned by CREATE PIXMAP. 


The arcs are drawn in the order they are listed in the array ares. For any 
given arc drawn with nonzero line widths, no pixel is drawn more than 
once. If arcs intersect, pixels are drawn multiple times. If the last point in 
one arc coincides with the first point in the following arc, the two arcs will 
join according to the join style. Angles are computed based on a coordinate 
system (before skewing either axis to form an ellipse). 


Specify the position and size of one arc in one arc data structure. 
For information about the arc data structure, see Section 6.4. 
DRAW ARCS uses the following members of the graphics context: 
¢ Function 

¢ Plane Mask 

e Join Style 

¢ Subwindow Mode 

* Cap Style 

¢ Graphics Exposures 

* Clip X Origin 

¢ Clip Y Origin 

¢ §=Clip Mask 

DRAW ARCS also uses the following mode-dependent members: 
¢ Foreground 


e Background 


¢ Tile 

* Stipple 

¢ Ts x origin 
¢ Ts y origin 
¢ Dash offset 
* Dash list 


For more information about the graphics context data structure and its 
members, see Section 5.1. 
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DRAW ARCS 
For more information about specifying the dimensions of an arc, or for 
information on drawing just one arc, refer to the DRAW ARC routine. 
For information about filling an arc, see the descriptions of the FILL ARC 
and FILL ARCS routines. 

X ERRORS 
VAX c Description 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 
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DRAW LINE 


Draws one line between two points in the specified window or pixmap. 





VAX FORMAT X$DRAW_LINE 
(display, drawable_id, gc_id, x1_coord, y1_coord, 
x2_coord, y2_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x1_coord longword longword read reference 
yi_coord longword longword read reference 
x2_coord longword longword read reference 
y2_coord longword longword read reference 





MITC FORMAT XDrawLine 
(display, drawable_id, gc_id, x1_coord, y1_coord, 
X2_coord, y2_coord) 


argument 
information XDrawLine (display, drawable id, gc_id, xl_coord, yl_coord, 
x2_coord, y2_coord) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
int xl_coord, yl_coord, x2_coord, y2_ coord; 





ARGUMENTS __ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) to draw the line in. The 
drawable identifier can be either a window or pixmap identifier. 


gc_id 

The identifier of the graphics context associated with the drawable. The 
identifier of the graphics context was originally returned by DEFAULT GC 
or CREATE GC. 
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DRAW LINE 
x1_coord 
The x-coordinate of the first point. This coordinate is relative to the origin 
of the drawable. The x1l- and yl-coordinates define the first point of the 
line. 
y1_coord 
The y-coordinate of the first point. This coordinate is relative to the origin 
of the drawable. The x1- and yi-coordinates define the first point of the 
line. 
x2_coord 
The x-coordinate of the second point. This coordinate is relative to the 
origin of the drawable. The x2- and y2-coordinates define the second point 
of the line. 
y2_coord 
The y-coordinate of the second point. This coordinate is relative to the 
origin of the drawable. The x2- and y2-coordinates define the second point 
of the line. 

DESCRIPTION DRAW LINE draws one line between the two specified points on a 
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drawable. If the drawable is a window, the identifier was originally 
returned by CREATE WINDOW or CREATE SIMPLE WINDOW. If the 
drawable is a pixmap, the identifier was originally returned by CREATE 
PIXMAP. 


DRAW LINE uses the following graphics context members to draw the line 
in the drawable: 


e Function 

e Plane Mask 

¢ Subwindow Mode 

¢ Graphics Exposures 

¢ Clip X Origin 

* Clip Y Origin 

e Clip Mask 

DRAW LINE also uses the following mode-dependent members: 


¢ Foreground 


¢ Background 
¢ Tile 

¢ Stipple 

¢ Ts x origin 
¢ Ts y origin 
¢ Dash offset 
¢ Dash list 


Graphics Routines 
DRAW LINE 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


When you want to draw more than one line, use DRAW LINES to draw 
connected lines or DRAW SEGMENTS to draw unconnected lines. Using 
DRAW LINE repeatedly is less efficient than using DRAW LINES or 


DRAW SEGMENTS. 





X ERRORS 


VAX 


X$C_BAD_DRAWABLE  BadDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 
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DRAW LINES 


Draws more than one connected line in the specified drawable. 





VAX FORMAT X$DRAW_LINES 
(display, drawable_id, gc_id, points, num_points, 


line_mode) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
points array x$point read reference 
num_points longword longword read reference 
line_mode longword longword read reference 





MITC FORMAT XDrawLines 
(display, drawable_id, gc_id, points, num_points, 
line_mode) 


argument 
information XDrawLines (display, drawable_id, gc_id, points, num_points, 
line_mode) 
Display *display; 
Drawable drawable _id; 
GC gc_id; 
XPoint *points; 
int num_points; 
int line mode; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) to draw the lines in. 
The drawable identifier can be either a window or pixmap identifier. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 
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points 
A pointer to an array of point data structures where each element defines 
a single point. The length of the array is specified by num_points. 


num_points 
The number of points to be drawn. This value defines the length of the 
array points. 


line_mode 

The coordinate mode of the points. The coordinates of the points can be 
relative to the drawable origin or to the previous point. The predefined 
values for mode are as follows: 


VAX Cc Description 

X$C_COORD_MODE = CoordModeOrigin The point coordinates are relative to 
the drawable origin. 

X$C_COORD_ CoordModePrevious The first point is relative to 

MODE_PREVIOUS the drawable origin and each 


subsequent point is relative to 
the point preceding it. 


Other values specified in this argument are not valid. 





DESCRIPTION 


DRAW LINES draws more than one line in the specified drawable. If the 
drawable is a window, the identifier was originally returned by CREATE 
SIMPLE WINDOW or CREATE WINDOW. If the drawable is a pixmap, 
the identifier was originally returned by CREATE PIXMAP. 


DRAW LINES draws lines from one point in the array points to the next 
point in the array. The lines are drawn in the same order as the points 
are listed in the array. For any given line with a nonzero width, no pixel 
is drawn more than once. If zero width (this) lines intersect, pixels are 
drawn multiple times. If wide lines intersect, the intersecting pixels are 
drawn only once. If the first and last points coincide, the first and last 
lines will join according to the join style specified in the graphics context. 


DRAW LINES uses the following members of the graphics context: 
¢ Function 

¢ Plane Mask 

¢ Subwindow Mode 

* Graphics Exposures 

¢ Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 

DRAW LINES also uses the following mode-dependent members: 

e Foreground 


¢ Background 
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DRAW LINES 
¢ Tile 
¢ Stipple 
¢ Ts x origin 
e Ts y origin 
¢ Dash offset 
¢ Dash list 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


The points can be drawn relative to the origin or relative to the previous 
point. Refer to Figure 6-13 for an illustration of how the mode changes 
the position of the points. 
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DRAW LINES 


Figure 6-13 Lines Drawn in Different Line Modes 


Coordinate Mode Origin 


Drawable Origin (5,5) 


Values supplied 
to the routine: 
Point 1=(5,5) 
Point 2=(10,10) 
Point 3=(15,15) 





Point 1 (10,10) 






Point 2 (15,15) 


Point 3 (20,20) 


Coordinate Mode Previous 


Drawable Origin (5,5) 


Values supplied 
to the routine: 
Point 1=(5,5) 
Point 2=(10,10) 
Point 3=(15,15) 





Point 1 (10,10) 








Point 2 (20,20) 


Point 3 (35,35) 
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When you want to draw a series of unconnected lines, use DRAW 
SEGMENTS. When you want to draw just one line, use DRAW LINE. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


¢ {na graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* — An input-only window is used as a 
drawable. 

¢« One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument's type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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DRAW POINT 


Draws a point in the specified window or pixmap. 





VAX FORMAT X$DRAW_POINT 
(display, drawable_id, gc_id, x_coord, y_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
X_coord longword longword read reference 
y_coord longword longword read reference 





MIT C FORMAT XDrawPoint 
(display, drawable_id, gc_id, x_coord, y_coord) 


argument 
information XDrawPoint (display, drawable_id, gc_id, x_coord, y_coord) 
Display *display; 
Drawable drawable _ id; 
GC gc_id; 
int x_coord, y_coord; 





ARGUMENTS _~ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the point will 
be drawn. The drawable identifier can be either a window or pixmap 
identifier. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by CREATE GC. 


x_coord 
The x-coordinate of the drawable where the point will be drawn. 


y_coord 
The y-coordinate of the drawable where the point will be drawn. 
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DRAW POINT 

DESCRIPTION DRAW POINT draws one point in the specified drawable. If the drawable 
is a window, the identifier was originally returned by CREATE SIMPLE 
WINDOW or CREATE WINDOW. If the drawable is a pixmap, the 
identifier was originally returned by CREATE PIXMAP. The identifier 
of the graphics context was originally returned by CREATE GC. 
DRAW POINT uses the following graphics context members to draw the 
point in the drawable: 
¢ Function 
e Plane Mask 
¢ Foreground 
¢ Subwindow Mode 
¢ Clip X Origin 
¢ Clip Y Origin 
¢ Clip Mask 
For more information about the graphics context data structure and its 
members, see Section 5.1. 
DRAW POINT is not affected by the tile or stipple pattern in the graphics 
context. 
When you want to draw more than one point, use DRAW POINTS. Using 
DRAW POINT repeatedly is less efficient than using DRAW POINTS. 

X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« — An input-only window is used as a 
drawable. 


*« One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 
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DRAW POINTS 


Draws more than one point in the specified drawable. 





VAX FORMAT X$DRAW_POINTS 
(display, drawable_id, gc_id, points, num_points, 
point_mode) 


argument 


information Argument Usage ~—~—=s‘dData Type +—~—~Access.-~=—=Ss Mechanism __ 


display identifier uns longword read reference 
drawabie_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
points array x$point read reference 
num_points longword longword read reference 
point_mode longword longword read reference 





MITC FORMAT XDrawPoints 
(display, drawable_id, gc_id, points, num_points, 
point_mode) 


argument 
information XDrawPoints (display, drawable id, gc_id, points, num_points, 
point_mode) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
XPoint *points; 
int num_points; 
int point_mode; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the points will 
be drawn. The drawable identifier can be either a window or pixmap 
identifier. If the drawable is a window, the identifier was originally 
returned by any CREATE WINDOW request. If the drawable is a pixmap, 
the identifier was originally returned by CREATE PIXMAP. 
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gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


points 
A pointer to an array of point data structures where each element defines 
a single point. The length of the array is specified by num_points. 


num_points 


The number of points to be drawn. This value defines the length of the 
array points. 


point_mode 

The coordinate mode of the points. The coordinates of the points can 
be relative to the drawable origin or relative to the previous point. The 
predefined values for point_mode are as follows: 


VAX c Description 

X$C_COORD_ CoordModeOrigin The point coordinates are relative to 
MODE_ORIGIN the drawable origin. 

X$C_COORD_ CoordModePrevious The first point is relative to 
MODE_PREVIOUS the drawable origin and each 


subsequent point is relative to 
the point preceding it. 


Other values specified in this argument are not valid. 





DESCRIPTION 


DRAW POINTS draws more than one point on the specified drawable. 


You specify the x- and y-coordinates in a point data structure for each 
point you want to draw. The point data structures are stored in the array 
points. 


For more information about the point data structure, see Section 6.1. 
DRAW POINTS uses the following members of the graphics context: 
¢ Function 

¢ Plane Mask 

¢ Foreground 

* Subwindow Mode 

¢ Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


Graphics Routines 
DRAW POINTS 


The points can be drawn relative to the origin or relative to the previous 


point. Refer to Figure 6-14 for an illustration of how the mode changes 
the position of the points. 


Figure 6-14 Points Drawn in Different Coordinate Modes 


Coordinate Mode Origin 


Drawable Origin (5,5) 





a supplied 
to the routine: 
Point 1=(5,5) @ Point 1 (10,10) 
Point 2=(10,10) 


Point 3=(15,15) w Point 2 (15,15) 


@ Point 3 (20,20) 


Coordinate Mode Previous 


Drawable Origin (5,5) 


one supplied 
to the routine: 
Point 1=(5,5) ™ Point 1 (10,10) 
Point 2=(10,10) 
Point 3=(15,15) 





m Point 2 (20,20) 


™ Point 3 (35,35) 
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When you want to draw just one point, use DRAW POINT. 


Graphics Routines 
DRAW POINTS 





X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_ MATCH BadMatch Possible causes are as follows: 


* In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

¢ — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* An input-only window lacks this 
attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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DRAW RECTANGLE 


Draws the outline of one rectangle in the specified drawable. 





VAX FORMAT X$DRAW_RECTANGLE 
(display, drawable_id, gc_id, x_coord, y_coord, width, 


height) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 





MITC FORMAT XDrawRectangle 
(display, drawable_id, gc_id, x_coord, y_coord, width, 
height) 


argument 
information XDrawRectangle(display, drawable id, gc_id, x_coord, y_coord, 
width, height) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
int x_coord, y coord; 
unsigned int width, height; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) to draw the rectangle 
in. The drawable identifier can be either a window or a pixmap identifier. 
If the drawable is a window, the identifier was originally returned by any 
CREATE WINDOW request. If the drawable is a pixmap, the identifier 
was originally returned by CREATE PIXMAP. 
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gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


x_coord 

The x-coordinate of the rectangle. This coordinate is relative to the origin 
of the drawable. The x- and y-coordinates define the upper left corner of 
the rectangle. 


y_coord 

The y-coordinate of the rectangle. This coordinate is relative to the origin 
of the drawable. The x- and y-coordinates define the upper left corner of 
the rectangle. 


width 
The width, in pixels, of the rectangle to be drawn. The width and height 
define the outline of the rectangle. 


height 
The height, in pixels, of the rectangle to be drawn. The width and height 
define the outline of the rectangle. 





DESCRIPTION 
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DRAW RECTANGLE draws a single rectangular outline in the specified 


rawable. 


The x- and y-coordinates (x_coord and y_coord) specify the position. The 
values you specify are relative to the origin of the drawable. The point 
defined by the coordinates is the upper left corner of the rectangle. The 
width and height specify the size. 


For example, the drawable has an origin at position (10,10). You specify 
the x-coordinate of the drawable origin as 10 and the y-coordinate of the 
drawable origin as 10. The upper left corner of the rectangle is at position 
(20,20). You specify the width and height of the rectangle as 10 and 5, 
respectively. The resulting rectangular outline is shown in Figure 6-15. 


Graphics Routines 
DRAW RECTANGLE 


Figure 6-15 Outline of a Rectangle 





Drawable Origin (10,10) 





Height (5) 





-_—_ OC 
Width (10) 
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DRAW RECTANGLE uses the following members of the graphics context: 
e =6Function 

e Plane Mask 

¢ Line Width 

¢ Line Style 

¢ Join Style 

¢ Subwindow Mode 

¢ Clip X Origin 

* Clip Y Origin 

¢ Clip Mask 

DRAW RECTANGLE also uses the following mode-dependent members: 
¢ Foreground 

¢ Background 

¢ Tile 

¢ Stipple 

e §6Ts x origin 

¢ Ts y origin 

¢ Dash offset 

¢ Dash list 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


When you want to draw several rectangles, use DRAW RECTANGLES. 
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For information about filling a rectangular outline, see the descriptions of 
the FILL RECTANGLE and FILL RECTANGLES routines. 





X ERRORS 
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VAX 


X$C_BAD_DRAWABLE BadDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window facks this 
attribute. 


Graphics Routines 
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DRAW RECTANGLES 


Draws the outline of more than one rectangle in the specified drawable. 





VAXFORMAT X$DRAW_RECTANGLES 
(display, drawable_id, gc_id, rectangles, 
num_rectangles) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
rectangles array x$rectangle read reference 
num_rectangles —longword longword read reference 





MITC FORMAT XDrawRectangles 
(display, drawable_id, gc_id, rectangles, 
num_rectangles) 


argument 
information XDrawRectangles (display, drawable_id, gc_id, rectangles, 
num_rectangles) 
Display *display; 
Drawable drawable_id; 
GC ge_id; 
XRectangle rectangles[]; 
int num_rectangles; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) to draw the rectangles 
in. The drawable identifier can be either a window or pixmap identifier. 
If the drawable is a window, the identifier was originally returned by 
CREATE SIMPLE WINDOW or CREATE WINDOW. If the drawable is a 
pixmap, the identifier was originally returned by CREATE PIXMAP. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 
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rectangles 

A pointer to an array of rectangle data structures where each element 
defines one rectangular outline. The rectangle data structure has members 
to specify the position and size of the rectangular outline. The length of 
the array is specified in num_rectangles. 


num_rectangles 
The number of rectangles to be drawn. This value specifies the length of 
the array in rectangles. 





DESCRIPTION 


DRAW RECTANGLES draws more than one rectangular outline in the 
specified drawable. The rectangles are drawn in the order they are listed 
in the array rectangles. For any given rectangle with a nonzero line 
width, no pixel is drawn more than once. If rectangles intersect, pixels are 
drawn multiple times. 


Specify the position and size of one rectangle in one rectangle data 
structure. The x- and y-coordinates (in the x_coord and y_coord members) 
specify the position. The values you specify are relative to the origin of the 
drawable. The point defined by the coordinates is the upper left corner of 
the rectangle. The width and height (in the width and height members) 
specify the size. 


For information about the rectangle data structure, see Section 6.3. 
DRAW RECTANGLES uses the following members of the graphics context: 
¢ Function 

¢ Plane Mask 

¢ Line Width 

* Line Style 

¢ Join Style 

¢ Subwindow Mode 

¢ Clip X Origin 

* Clip Y Origin 

¢ Clip Mask 

DRAW RECTANGLES also uses the following mode-dependent members: 


¢ Foreground 


¢ Background 
¢ Tile 
¢ Stipple 


¢ Ts x origin 


¢ Ts y origin 
¢ Dash offset 
e Dash list 
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For more information about the graphics context data structure and its 
members, see Section 5.1. 


When you want to draw just one rectangle, use DRAW RECTANGLE. 


For information about filling a rectangular outline, see the descriptions of 
the FILL RECTANGLE and FILL RECTANGLES routines. 





X ERRORS 


VAX 


X$C_BAD_DRAWABLE  BacDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 
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DRAW SEGMENTS 


Draws more than one line in the specified drawable. The lines are not 
connected unless specified. 





VAXFORMAT X$DRAW_SEGMENTS 
(display, drawable_id, gc_id, segments, 
num_segments) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
ge_id identifier uns longword read reference 
segmenis array x$segment read reference 
num_segments — longword longword read reference 





MITC FORMAT XDrawSegmenis 
(display, drawable_id, gc_id, segments, 
num_segments) 


argument 
information XDrawSegments (display, drawable_id, gc_id, segments, 
num_segments) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
XSegment *segments; 
int num_segments; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) to draw the lines in. 
The drawable identifier can be either a window or a pixmap identifier. 
If the drawable is a window, the identifier was originally returned by 
CREATE SIMPLE WINDOW or CREATE WINDOW. If the drawable is a 
pixmap, the identifier was originally returned by CREATE PIXMAP. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


Graphics Routines 
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segments 

A pointer to an array of segment data structures where each entry defines 
two points. The line is drawn between the two points. The coordinates 
defining the points are relative to the origin of the drawable. The length 
of the array is specified by num_segments. 


num_segments 
The number of lines to be drawn. This value defines the length of the 
array segments. 





DESCRIPTION 


DRAW SEGMENTS draws more than one line in the specified drawable. 


DRAW SEGMENTS uses the points defined in the segment data structures 
to draw each line. The lines are drawn in the order they are stored in the 
array. The lines are not connected by a join when you specify a common 
point. Segments sharing common endpoints will not be joined with the 
graphics context’s join style. You specify the two points for each line 
within the segment data structure. Refer to Section 6.2 for an illustration 
of this data structure. Use the X1 and Yl members to define one point; 
use the X2 and Y2 members to define the second point. 


For information about the segment data structure, see Section 6.2. 


For any given line, no pixel is drawn more than once. If lines intersect, 
pixels are drawn multiple times. The lines are drawn separately, without 
regard to the join style member specified by the graphics context. 


DRAW SEGMENTS uses the following members of the graphics context: 
* Function 

e Plane Mask 

¢ Line Width 

¢ Line Style 

* Cap Style 

e Subwindow Mode 

¢ Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 

DRAW SEGMENTS also uses the following mode-dependent members: 
¢ Foreground 

¢ Background 

¢ Tile 

* Stipple 
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¢ Ts x origin 


e Ts y origin 
* Dash offset 
¢ Dash list 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


When you want to draw a series of connected lines, use DRAW LINES. 
When you want to draw just one line, use DRAW LINE. 





X ERRORS 
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VAX Cc Description 


X$C_BAD_DRAWABLE BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


« In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 
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FILL ARC 


Fills in either a pie slice or chord area of an arc in the specified drawable. 





VAX FORMAT X$FILL_ARC 
(display, drawable_id, gc_id, x_coord, y_coord, width, 
height, angle1, angle2) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 
angle longword longword read reference 
angle2 longword longword read reference 





MITC FORMAT XFillArc 
(display, drawable_id, gc_id, x_coord, y_coord, width, 
height, angle1, angle2) 


argument 
information XFillArc(display, drawable id, gc_id, x_coord, y_ coord, width, 
height, anglel, angle2) 
Display *display; 
Drawable drawable_id; 
GC go_id; 
int x_coord, y_coord; 
unsigned int width, height; 
int anglel, angle2; 





ARGUMENTS _ displa 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the arc is. The 
drawable identifier can be either a window or pixmap identifier. If the 
drawable is a window, the identifier was originally returned by CREATE 
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WINDOW or CREATE SIMPLE WINDOW. If the drawable is a pixmap, 
the identifier was originally returned by CREATE PIXMAP. 


ge_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


x_coord 

The x-coordinate of the rectangle used to define the arc. This coordinate is 
relative to the origin of the drawable. The x- and y-coordinates define the 
upper left corner of the rectangle. 


y_coord 

The y-coordinate of the rectangle used to define the arc. This coordinate is 
relative to the origin of the drawable. The x- and y-coordinates define the 
upper left corner of the rectangle. 


width 


The width, in pixels, of the rectangle used to define the arc. The width 
and height are the major and minor axes of the arc. 


height 
The height, in pixels, of the rectangle used to define the arc. The width 
and height are the major and minor axes of the arc. 


angle 

The angle to specify the start of the arc relative to the three o’clock 
position from the center. This value is in degrees, scaled by 64 with 
positive indicating counterclockwise motion and negative indicating 
clockwise motion. 


angle2 

The angle to specify the path and extent of the arc relative to the start 
of the arc. This value is in degrees, scaled by 64 with positive indicating 
counterclockwise motion and negative indicating clockwise motion. 
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FILL ARC fills the area defined by one arc in the specified drawable. 


The pattern used and the area filled in the arc is specified by the fill style 
and arc mode members of the associated graphics context. The arc mode 
specifies whether the pie slice or chord area is filled. 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


FILL ARC uses the following graphics context members: 
¢ Function 

e Plane Mask 

e §6Fill Style 

¢ Arc Mode 

¢ Subwindow Mode 


* Clip X Origin 


* Clip Y Origin 


¢ Clip Mask 


Graphics Routines 
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FILL ARC also uses the following mode-dependent members: 


e Foreground 
¢ Background 
¢ Tile 

e Stipple 

° Ts x origin 


e Ts y origin 


When you want to fill in more than one arc, use FILL ARCS. Using FILL 
ARCS is more efficient than using FILL ARC repeatedly. 


For information about drawing and specifying the dimensions of an arc, 
see the description of the DRAW ARC routine. 





X ERRORS 


VAX 


X$C_BAD_DRAWABLE  BadDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 
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FILL ARCS 


Fills in either a pie slice or a chord area of more than one arc in the specified 
window or pixmap. 





VAX FORMAT 


argument 
information 


X$FILL_ARCS 
(display, drawable_id, gc_id, arcs, num_arcs) 


Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
ge_id identifier uns longword read reference 
arcs array x$arc read reference 
num_arcs longword longword read reference 





MITC FORMAT XFillArcs 


argument 
information 


(display, drawable_id, gc_id, arcs, num_arcs) 


XFillArcs (display, drawable_id, gc_id, arcs, num_arcs) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
XArce *arcs; 
int num_arcs; 





ARGUMENTS 
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display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the arcs are. 
The drawable identifier can be either a window or pixmap identifier. If the 
drawable is a window, the identifier was originally returned by CREATE 
WINDOW or CREATE SIMPLE WINDOW. If the drawable is a pixmap, 
the identifier was originally returned by CREATE PIXMAP. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 
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arcs 
A pointer to an array of arc data structures, where each element defines 
one arc to be filled in. The length of the array is specified by num_arcs. 


num_arcs 
The number of arcs to be filled in. This value specifies the length of the 
array arcs. 





DESCRIPTION 


FILL ARCS fills areas defined by arcs in the specified drawable. 


The identifier of the graphics context associated with the drawable was 
originally returned by DEFAULT GC or CREATE GC. 


The arcs are filled in according to their order in the array. For any one 
arc, no pixel is drawn more than once. If filled areas intersect, pixels are 
drawn multiple times. 


The pattern used and the area filled in the arc is specified by the fill style 
and arc mode members of the associated graphics context. The arc mode 
specifies whether the pie slice or chord area is filled. 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


FILL ARCS uses the following graphics context members: 
¢ Function 


e Plane Mask 
¢ Fill Style 
e Arc Mode 


¢ Subwindow Mode 

¢ Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 

FILL ARCS also uses the following mode-dependent members: 


¢ Foreground 


¢ Background 
¢ Tile 

¢ Stipple 

e =6Ts x origin 
¢ Ts y origin 


For information about drawing and specifying the dimensions of an arc, 
see the description of the DRAW ARC routine. 


When you want to fill one arc, use FILL ARC. 
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X ERRORS 


VAX Cc Description 


X$C_BAD_DRAWABLE  BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 
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FILL POLYGON 


Fills a polygon within a specified drawable. 





VAX FORMAT X$FILL_POLYGON 
(display, drawable_id, gc_id, points, num_points, 
shape, mode) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
points array x$point read reference 
num_points longword longword read reference 
shape longword longword read reference 
mode longword longword read reference 





MIT C FORMAT XFillPolygon 
(display, drawable_id, gc_id, points, num_points, 
shape, mode) 


argument 
information XFillPolygon(display, drawable_id, gc_id, points, num_points, 
shape, mode) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
XPoint *points; 
int num_points; 
int shape; 
int mode; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the rectangle 
will be filled. The drawable identifier can be either a window or pixmap 
identifier. If the drawable is a window, the identifier was originally 
returned by CREATE WINDOW or CREATE SIMPLE WINDOW. If the 
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drawable is a pixmap, the identifier was originally returned by CREATE 
PIXMAP. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


points 

A pointer to an array of points that define the polygon shape. Each 
element in the array is a point data structure. Within the point data 
structure, the x- and y-coordinates of a point are specified. A path is 
drawn from one point in the array to the next. This path defines the 
polygon. The length of the array is specified in num_points. 


num_points 
The number of points in the polygon. This defines the length of the array 
in points. 


shape 
The shape of the polygon. The predefined values for shape are as follows: 


VAX Cc Description 

X$C_POLYCOMPLEX Complex The polygon outline can intersect itself 
X$C_CONVEX Convex The polygon is wholly convex 
X$C_NONCONVEX Nonconvex The polygon outline does not intersect itself 


Other values specified in this argument are not valid. 


If the shape of the polygon is known and correctly specified with this 
argument, server performance can be improved. If the shape is specified 
incorrectly, the result of the operation will be undefined. 


mode 

The coordinate mode of the points. The coordinates of the points can 
be relative to the drawable origin or relative to the previous point. The 
predefined values for mode are as follows: 


VAX Cc Description 

X$C_COORD_ CoordModeOrigin The point coordinates of each point 
MODE_ORIGIN are relative to the drawable origin. 
X$C_COORD_ CoordModePrevious The first point is relative to 
MODE_PREVIOUS the drawable origin and each 


subsequent point is relative to 
the point preceding it. 


Other values specified in this argument are not valid. 
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DESCRIPTION 


FILL POLYGON fills in the area of a multi-sided shape in the specified 
window or pixmap (drawable). The fill pattern is specified by the fill style 
member in the associated graphics context. 


Specify the polygon outline by defining point coordinates in the points 

array. Lines are drawn between the points. If the last point in the list 

does not coincide with the first point to close the polygon, it is closed by 
the routine. No pixel is drawn more than once. 


The first point in the array is always relative to the origin of the drawable. 
Subsequent points can be drawn relative to the origin or relative to the 
previous point. Refer to Figure 6-16 for an illustration of how the mode 
changes the position of the points. 


The polygon is filled according to the fill pattern and fill rule specified in 
the graphics context. 


The points array uses a predefined point data structure. This data 
structure has members for the x- and y-coordinates that define one point. 


For information about the point data structure, see Section 6.1. 
FILL POLYGON uses these graphics context members: 

e Function 

e Plane Mask 

¢ Fill Style 

e Fill Rule 

¢ Subwindow Mode 

* Clip X Origin 

¢ Clip Y Origin 

¢ Clip Mask 

FILL POLYGON also uses the following mode-dependent members: 
* Foreground 


e Background 


« Tile 

¢ Stipple 

e Ts x origin 
e §6Ts y origin 


For more information about the graphics context data structure and its 
members, see Section 5.1. 
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Figure 6-16 Polygon Shapes Drawn in Different Coordinate Modes 





Origin 
Drawable Origin (5,5) 

Values supplied Points 1 and 5 (10,10) 
to the routine: Point 4 (20,10) 
Point 1=(5,5) ae | 
Point 2=(10,10) Point 3 (20,15) 
Polnt s=115,10) Point 2 (15,15) 
Point 4=(15,5) , 
Point 5=(5,5) 

Previous 


Drawable Origin (5,5) 





Values supplied 
to the routine: 
Point 1= =(5, > 


Point 1 (10,10) 










=(15.5) a Automatically Closed 
5,5) Point 2 (20,20) 


Point 3 (35,30) 
Point 4 (50,35) 


Point 5 (55,40) 


ZK-0016A-GE 
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X ERRORS 


VAX Cc 
X$C_BAD_DRAWABLE __ BadDrawable 


X$C_BAD_GC BadGC 


X$C_BAD_MATCH BadMatch 


X$C_BAD_VALUE BadValue 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


¢ In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

« An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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FILL RECTANGLE 


Fills the area defined by a rectangular outline in the specified drawable. 





VAX FORMAT X$FILL_RECTANGLE 
(display, drawable_id, gc_id, x_coord, y_coord, width, 


height) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gce_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 





MITC FORMAT XFillRectangle 
(display, drawable_id, gc_id, x_coord, y_coord, width, 
height) 


argument 
information XFillRectangle (display, drawable_id, gc_id, x_coord, y_coord, 
width, height) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x_coord, y coord; 
unsigned int width, height; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the rectangle 
will be filled. The drawable identifier can be either a window or pixmap 
identifier. 


gc_id 


The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 
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x_coord 

The x-coordinate of the rectangle. This coordinate is relative to the origin 
of the drawable. The x- and y-coordinates define the upper left corner of 
the rectangle. 


y_coord 

The y-coordinate of the rectangle. This coordinate is relative to the origin 
of the drawable. The x- and y-coordinates define the upper left corner of 
the rectangle. 


width 
The width, in pixels, of the rectangle. The width and height define the size 
of the rectangular area to be filled. 


height 
The height, in pixels, of the rectangle. The width and height define the 
size of the rectangular area to be filled. 





DESCRIPTION 


FILL RECTANGLE fills in a rectangular area in the specified window. 
The fill pattern used is specified in the fill style graphics context member. 


FILL RECTANGLE uses the following members of the graphics context: 
¢ Function 

¢ Plane Mask 

¢ Fill Style 

e Subwindow Mode 

¢ Clip X Origin 

¢ Clip Y Origin 

e Clip Mask 

FILL RECTANGLE also uses the following mode-dependent members: 


¢ Foreground 


¢ Background 
e §6Tile 

¢ Stipple 

e §6Ts x origin 
¢ Ts y origin 


For more information about the graphics context data structure and its 
members, see Section 5.1. 


When you want to fill more than one rectangular area, use FILL 
RECTANGLES. Using FILL RECTANGLE repeatedly is less efficient 
than using FILL RECTANGLES, 


For information on drawing a rectangular outline, see the descriptions of 
the DRAW RECTANGLE and DRAW RECTANGLES routines. 
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X ERRORS 


VAX c Description 


X$C_BAD_DRAWABLE _ BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

X$C_BAD_GC BadGC A value that you specified for a graphics 


context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 
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FILL RECTANGLES 


Fills the areas defined by rectangular outlines in the specified drawable. 





VAX FORMAT X$FILL_RECTANGLES 
(display, drawable_id, gc_id, rectangles, 
num_rectangles) 


argument 

information Argument Usage Data Type Access Mechanism 
dispiay identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
rectangles array x$rectangle read reference 
num_rectangles longword longword read reference 





MITC FORMAT XFillRectangles 
(display, drawable_id, gc_id, rectangles, 
num_rectangles) 


argument 
information XFillRectangles(display, drawable _id, gc_id, rectangles, 
num_rectangles) 
Display *display; 
Drawable drawable id; 
GC ge_id; 
XRectangle *rectangles; 
int num_rectangles; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the window or pixmap (drawable) where the rectangle 
will be filled. The drawable identifier can be either a window or pixmap 
identifier. 


gc_id 


The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 
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DESCRIPTION 
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rectangles 

A pointer to an array of rectangles, where each element defines a 
rectangular area to be filled. Each element is a rectangle data structure. 
The x- and y-coordinates define the upper left corner of the rectangle and 
are relative to the origin of the drawable. The rectangular area within 
each data structure is defined by the width and height. The length of the 
array is defined by num_rectangles. 


For information about the rectangle data structure, see Section 6.3. 
num_rectangles 


The number of rectangular areas to be filled. This value specifies the 
length of the array in rectangles. 


FILL RECTANGLES fills in rectangular areas in the specified window 
or pixmap (drawable). The area filled is within the outline defined by 
the rectangle. The fill pattern is specified by the fill style member in the 
associated graphics context. 


The rectangles are filled in the order listed in the array rectangles. For 
any given rectangle, no pixel is drawn more than once. If rectangles 
intersect, the pixel is drawn multiple times. 


For information about the rectangle data structure, see Section 6.3. 


The x- and y-coordinates (in the x_coord and y_coord members) specify 
the position. The values you specify are relative to the origin of the 
drawable. The point defined by the coordinates is the upper left corner of 
the rectangle. The width and height (in the width and height members) 
specify the size. 


FILL RECTANGLES uses the following members of the graphics context: 
* Function 

¢ Plane Mask 

¢ Fill Style 

¢ Subwindow Mode 

* Clip X Origin 

* Clip Y Origin 

¢ Clip Mask 

FILL RECTANGLES also uses the following mode-dependent members: 


e Foreground 


¢ Background 
¢ Tile 

¢ Stipple 

¢ Ts x origin 
e Ts y origin 
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For information about the graphics context data structure and its 
members, see the Section 5.1. 


When you want to fill one rectangular area, use FILL RECTANGLE. 


For information on drawing a rectangular outline, see the descriptions of 
the DRAW RECTANGLE and DRAW RECTANGLES routines. 





X ERRORS 


VAX 


X$C_BAD_DRAWABLE BadDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 
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GET IMAGE 


Returns the contents of a rectangle to the specified image structure. 





VAX FORMAT _ siatus_return = X$GET_IMAGE 
(display, drawable_id, x_coord, y_coord, width, height, 
plane_mask, image_format, ximage_return) 


argument 


information 


status_return longword longword write value 

display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 
plane_mask mask_longword uns longword read reference 
image_format longword longword read reference 
ximage_return record x$image write reference 





MITC FORMAT ximage_return=XGetlImage 
(display, drawable_id, x_coord, y_coord, width, height, 
plane_mask, image_format) 


argument 
information XImage *xGet Image (display, drawable_id, x coord, y_ coord, width, 
height, plane mask, image_format) 
Display *display; 
Drawable drawable_id; 
int x_coord, y_ coord; 
unsigned int width, height; 
long plane_mask; 
int image_format; 





RETURNS status_return (VAX only) 


Specifies whether or not the routine completed successfully. 


ximage_return (MIT C only) 


A pointer to an image data structure containing the data requested. 
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ARGUMENTS 


display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) where the image data 
will be returned. 


x_coord 

The x-coordinate of the rectangle to retrieve image data from. This 
coordinate is relative to the origin of the drawable. The x- and 
y-coordinates define the upper left corner of the rectangle. 


y_coord 


The y-coordinate of the rectangle to retrieve image data from. This 
coordinate is relative to the origin of the drawable. The x- and 
y-coordinates define the upper left corner of the rectangle. 


width 


The width, in pixels, of the rectangle. 


height 
The height, in pixels, of the rectangle. 


plane_mask 
A bit mask specifying the planes to be retrieved. 


image_format 


The format of the image. The predefined values for format are as follows: 


VAX Cc Descriptiopn 


X$C_XY_BITMAP XYBitmap XY bitmap format 
X$C_XY_PIXMAP XYPixmap XY pixmap format 
X$C_Z_PIXMAP ZPixmap Z pixmap format 


Other values specified in this argument are not valid. 


ximage_return (VAX only) 


The returned image data structure containing the requested data. 





DESCRIPTION 


GET IMAGE returns an image data structure that contains the data 
for the rectangular image requested. If the drawable is a window, the 
identifier was originally returned by CREATE SIMPLE WINDOW or 
CREATE WINDOW. If the drawable is a pixmap, the identifier was 
originally returned by CREATE PIXMAP. 


If the value of format is XY bitmap or XY pixmap, only the bit planes 
specified in plane_mask are returned. If the value of format is Z pixmap, 
all bits in all planes not specified in plane_mask are set to zero. 
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GET IMAGE returns the depth of the image to the depth member of the 
image data structure. The depth is defined by the depth of the drawable 
when the drawable was created, except when getting a subset of the planes 
in XY Pixmap format, where the depth is given by the number of bits set 


to 1 in plane_mask. 


If the drawable is a window, the window must be mapped. The rectangular 
area would be contained within the window, including its borders, if the 
window were fully visible. In addition, the rectangular area must be fully 
contained within pixmaps. The returned image will include any visible 
portions of subwindows or overlapping windows contained in the rectangle. 





X ERRORS 
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VAX 


X$C_BAD_DRAWABLE  BadDrawable 


X$C_BAD_MATCH 


X$C_BAD_VALUE 


Cc 


BadMatch 


BadValue 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


Possible causes are as follows: 


In a graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argumenit’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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GET PIXEL 

Obtains the value of one pixel stored in an image. 

VAX FORMAT _ pixel_value_return=X$GET_PIXEL 

(ximage, x_coord, y_coord) 

argument 

information Argument Usage Data Type Access Mechanism 
pixel_value_return longword uns longword write reference 
ximage record x$image read reference 
X_coord longword longword read reference 
y_coord longword longword read reference 





MIT C FORMAT _pixel_value_return=XGetPixel 
(ximage, x_coord, y_coord) 





argument 

information unsigned long XGetPixel (ximage, x_coord, y_ coord) 
XImage *ximage; 
int x_coord; 
int y_ coord; 

RETURNS pixel_value_return 


The value of the pixel, as stored in the image. The pixel value is returned 
in normalized format (in other words, the least significant byte of the 
longword is the least significant byte of the pixel). 





ARGUMENTS ' = _ ximage 


The image data structure containing the pixel. 


For information about the image data structure, see Section 6.5. 


x_coord 

The x-coordinate of the pixel within the pixmap of the image. This 
coordinate is relative to the origin of the image. The x- and y-coordinates 
define the location of the pixel to obtain the value for. 


y_coord 

The y-coordinate of the pixel within the pixmap of the image. This 
coordinate is relative to the origin of the image. The x- and y-coordinates 
define the location of the pixel to obtain the value for. 
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DESCRIPTION = GET PIXEL returns a pixel value (index in a pixmap) for the specified 
pixel. The specified pixel is contained with the pixmap that stores the 
image. The image data structure specified in ximage specifies the exact 
pixmap. 
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GET SUBIMAGE 


Returns the contents of a rectangle to a location within a specified preexisting 
image structure. 





VAX FORMAT _ siatus_return = X$GET_SUB_IMAGE 
(display, drawable_id, x_coord, y_coord, width, height, 
plane_mask, image_format, dst_ximage_return, 
dst_x_coord, dst_y_coord) 


argument 

information Argument Usage Data Type Access Mechanism 
status_return longword longword write value 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 
plane_mask mask_longword uns longword read reference 
image_format longword longword read reference 
dst_ximage_ record x$image write reference 
return 
dst_x_coord longword longword read reference 
dst_y_coord longword longword read reference 





MITC FORMAT ximage_return=XGetSublmage 
(display, drawable_id, x_coord, y_coord, width, height, 
plane_mask, image_format, dst_ximage_return, 
dst_x_coord, dst_y_coord) 


Graphics Routines 


GET SUBIMAGE 


argument 
information 





RETURNS 





ARGUMENTS 
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XImage *XGetSubImage (display, drawable_id, x_coord, y_ coord, 
width, height, plane_mask, image_format, 


dst_ximage_return, dst_x_coord, dst_y_coord) 


Display *display; 

Drawable drawable_id; 

int x_coord, y coord; 
unsigned int width, height; 
long plane_mask; 

int image_format; 

XImage dst_ximage_ return; 

int dst_x coord, dst_y coord; 


status_return (VAX only) 


Return value that specifies whether the routine completed successfully. 


ximage_return (MIT C only) 


A pointer to a preexisting source image data structure containing the data 


requested. 


display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 


The identifier of the window or pixmap (drawable) where the image data 


will be returned. 


x_coord 

The x-coordinate of the rectangle to retrieve image data from. This 
coordinate is relative to the origin of the drawable. The x- and 
y-coordinates define the upper left corner of the rectangle. 


y_coord 

The y-coordinate of the rectangle to retrieve image data from. This 
coordinate is relative to the origin of the drawable. The x- and 
y-coordinates define the upper left corner of the rectangle. 


width 


The width, in pixels, of the rectangle. 


height 
The height, in pixels, of the rectangle. 


plane_mask 
A bit mask specifying the planes to be retrieved. 
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image_format 


The format of the image. The predefined values for format are as follows: 


VAX Cc Descriptiopn 
X$C_XY_BITMAP XYBitmap XY bitmap format 
X$C_XY_PIXMAP XYPixmap XY pixmap format 
X$C_Z_PIXMAP ZPixmap Z pixmap format 


Other values specified in this argument are not valid. 


dst_ximage_return 
The returned destination image data structure. 


dst_x_coord 

The x-coordinate of the destination rectangle. This coordinate is relative 
to the origin of the drawable. The destination x- and y-coordinates define 
the upper left corner of the destination rectangle and determine where the 
subimage will be placed within the destination image. 


dst_y coord 

The y-coordinate of the destination rectangle. This coordinate is relative 
to the origin of the drawable. The destination x- and y-coordinates define 
the upper left corner of the destination rectangle and determine where the 
subimage will be placed within the destination image. 





DESCRIPTION 


GET SUBIMAGE returns the contents of a rectangle to a location within 
a specified preexisting image structure. If the drawable is a window, 
the identifier was originally returned by CREATE SIMPLE WINDOW 
or CREATE WINDOW. If the drawable is a pixmap, the identifier was 
originally returned by CREATE PIXMAP. 


If the value of image_format is XY bitmap or XY pixmap, only the bit 
planes specified in plane_mask are returned. If the value of 
image_format is Z pixmap, all bits in all planes not specified in 
plane_mask are set to zero. 


GET SUB IMAGE does not update any fields in the destination image data 
structure. The depth of the destination image structure must be the same 
as the depth of the drawable. If the specified subimage does not fit at the 

specified location on the destination image, the right and bottom edges are 
clipped. 


If the drawable is a window, the window must be mapped. The rectangular 
area would be contained within the window, including its borders, if the 
window were fully visible. In addition, the rectangular area must be 
fully contained within pixmaps. The returned image includes any visible 
portions of subwindows or overlapping windows contained in the rectangle. 
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X ERRORS 


VAX c Description 


X$C_BAD_DRAWABLE _BadDrawable A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


X$C_BAD_MATCH BadMatch Possible causes are: 


* Ina graphics request, the root and 
depth of the graphics context does 
not match that of the drawable. 

¢ — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

« — An input-only window lacks this 
attribute. 


X$C_BAD_VALUE BadValue Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument’s type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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PUT IMAGE 


Combines the image in memory with the image in a specified rectangle on the 
specified drawable. 





VAX FORMAT X$PUT_IMAGE 
(display, drawable_id, gc_id, ximage, src_x_coord, 
src_y_coord, dst_x_coord, dst_y_coord, width, height) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
ximage record x$image read reference 
src_x_coord longword longword read reference 
src_y_coord longword longword read reference 
dst_x_coord longword longword read reference 
dst_y_coord longword longword read reference 
width longword longword read reference 
height longword longword read reference 





MITC FORMAT XPutimage 
(display, drawable_id, gc_id, ximage, src_x_coord, 
src_y_coord, dst_x_coord, dst_y_coord, width, height) 


argument 
information XPutImage (display, drawable id, gc_id, ximage, srce_x_coord, 
src_y_coord, dst_x_ coord, dst_y coord, width, height) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
XImage *ximage; 
int src_x coord, src_y coord; 
int dst_x coord, dst_y coord; 
unsigned int width, height; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 
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drawable_id 

The identifier of the window or pixmap (drawable) containing the image 
data. If the drawable is a window, the identifier was originally returned 
by CREATE SIMPLE WINDOW or CREATE WINDOW. If the drawable is 
a pixmap, the identifier was originally returned by CREATE PIXMAP. 


gc_id 
The identifier of the graphics context associated with the drawable. This 
identifier was originally returned by DEFAULT GC or CREATE GC. 


ximage 


The image to be combined with the rectangle. 


src_x_coord 

The x-coordinate specifying the offset from the left edge of the image in 
memory, specified by the image data structure. The source x- and 
y-coordinates specify the beginning point of the image in memory that will 
be combined with the image in the drawable. 


src_y_coord 

The y-coordinate specifying the offset from the top edge of the image in 
memory, specified by the image data structure. The source x- and 
y-coordinates specify the beginning point of the image in memory that will 
be combined with the image in the drawable. 


dst_x_coord 

The x-coordinate of the rectangle defining the image in the drawable. This 
coordinate is relative to the origin of the drawable. The destination 

x- and y-coordinates define the upper left corner in the drawable that will 
be combined with the image in memory. 


dst_y_ coord 

The y-coordinate of the rectangle defining the image in the drawable. This 
coordinate is relative to the origin of the drawable. The destination 

x- and y-coordinates define the upper left corner in the drawable that will 
be combined with the image in memory. 


width 


The width of the rectangular area defining the image in memory to be 
combined with the image in the drawable. 


height 
The height of the rectangular area defining the image in memory to be 
combined with the image in the drawable. 





DESCRIPTION 


PUT IMAGE combines an image in memory with an image in a drawable. 


Define the portion of the image in memory that you want to combine. That 
subimage is combined with the image that is currently displayed in the 
drawable at the position specified by dst_x_coord and dst_y_coord. If 
XY bitmap format is used, then the depth must be one. For XY pixmap 
and Z pixmap, the depth must match the depth of the drawable. For XY 
pixmap, the image must be sent in XY format. For Z pixmap, the image 
must be sent in the Z format defined for the given depth. 
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PUT IMAGE uses the following graphics context members: 


¢ Function 

e Plane Mask 

¢ Subwindow Mode 
¢ Clip X Origin 

* Clip Y Origin 

¢ Clip Mask 


For XY bitmap images only, PUT IMAGE also uses the foreground and 
background mode-dependent graphics context members. The foreground 
value is used for all one bits in the image and the background value is 


used for all zero bits in the image. 





X ERRORS 


VAX Cc 
X$C_BAD_DRAWABLE  BadDrawable 


X$C_BAD_GC BadGC 


X$C_BAD_MATCH BadMatch 


X$C_BAD_VALUE BadValue 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are as follows: 


* Ina graphics request, the root and 
depth of the graphics context do not 
match those of the drawable. 

* An input-only window is used as a 
drawable. 

*« One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

« — An input-only window lacks this 
attribute. 


Some numeric values fall outside the 
range of values accepted by the request. 
Unless a specific range is specified for 
an argument, the full range defined by 
the argument's type is accepted. Any 
argument defined as a set of alternatives 
can generate this error. 
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PUT PIXEL 


Changes one pixel value within the pixmap containing an image. 





VAX FORMAT X$PUT_PIXEL 
(ximage, X_coord, y_coord, pixel) 


argument 

information Argument Usage Data Type Access Mechanism 
ximage record x$image read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
pixel longword uns longword read reference 





MITC FORMAT XPutPixel 
(ximage, x_coord, y_coord, pixel) 


argument 
information int XPutPixel(ximage, x_coord, y_coord, pixel) 
XImage *ximage; 
int x coord; 
int y_coord; 
unsigned long pixel; 





ARGUMENTS '-  ximage 


The image data structure containing the pixel to be changed. 


For information about the image data structure, see Section 6.5. 


x_coord 

The x-coordinate of the pixel within the pixmap of the image. This 
coordinate is relative to the origin of the image. The x- and y-coordinates 
define the location of the pixel to be changed. 


y_coord 

The y-coordinate of the pixel within the pixmap of the image. This 
coordinate is relative to the origin of the image. The x- and y-coordinates 
define the location of the pixel to be changed. 


pixel 

The new value of the pixel. The pixel value must be in normalized format 
(in other words, the least significant byte of the longword is the least 
significant byte of the pixel). 
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DESCRIPTION = PUT PIXEL changes the value of one pixel within a pixmap containing an 
image. The pixmap is specified with the image data structure. You specify 
the new pixel value in pixel. 
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SUBIMAGE 


Creates a new image from an existing image. 





VAX FORMAT X$SUB_IMAGE 
(ximage, x_coord, y_coord, width, height, 
sub_image_return) 


argument 

information Argument Usage Data Type Access Mechanism 
ximage record x$image read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
width longword uns longword read reference 
height longword uns longword read reference 
sub_image_return record xsimage write reference 





MITC FORMAT  sub_image_return=XSublmage 
(ximage, x_coord, y_coord, width, height) 


argument 
information XImage *XSubImage(ximage, x_coord, y_ coord, width, height) 
XImage *ximage; 
int x_coord; 
int y_coord; 
int width; 
int height; 





RETURNS sub_image_return (C only) 


A pointer to the image data structure created for the new sub image. 





ARGUMENTS = ximage 


A pointer to the image data structure that references the existing image to 
create the new image. 


x_coord 

The x-coordinate of the existing image. This coordinate is relative to origin 
of the image. The x- and y-coordinates define the point within the existing 
image where copying will start. 
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y_coord 

The y-coordinate of the existing image. This coordinate is relative to origin 
of the image. The x- and y-coordinates define the point within the existing 
image where copying will start. 


width 
The width, in pixels, of the new subimage. The width and height 
determine the area of the new subimage. 


height 
The height, in pixels, of the new subimage. The width and height 
determine the area of the new subimage. 


sub_image_return (VAX only) 


A pointer to the image data structure created for the new subimage. 





DESCRIPTION 


SUBIMAGE copies a portion of an existing image to create a new image. 
In the MIT C binding, it also allocates memory sufficient for a new image 
data structure that references the subimage; the pointer to the subimage’s 
data structure is returned. 


SUBIMAGE creates the new image by repeating GET PIXEL and PUT 
PIXEL calls. Therefore, this operation might be slow. 
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Use the text routines to perform the following tasks: 


¢ Computing string sizes 


¢ Returning the logical extents of strings 


¢ Drawing text 


For concepts related to text routines and information on how to use text 
routines, see the VMS DECwindows Xlib Programming Volume. 


The routines described in this chapter are listed in Table 7-1. 


Table 7—1 Text Routines 


Routine Name 


DRAW IMAGE STRING 


DRAW IMAGE STRING 16 


DRAW STRING 


DRAW STRING 16 


DRAW TEXT 


DRAW TEXT 16 


QUERY TEXT EXTENTS 


QUERY TEXT EXTENTS 16 


TEXT EXTENTS 


TEXT EXTENTS 16 


TEXT WIDTH 


TEXT WIDTH 16 


Description 


Draws a string of 8-bit character image text to 
the screen. 


Draws a string of 16-bit character image text 
to the screen. 


Draws a text string (8-bit characters) to the 
screen in a single font. 


Draws a text string (16-bit characters) to the 
screen in a single font. 


Draws text (8-bit characters) to the screen in 
various fonts. 


Draws text (16-bit characters) to the screen in 
various fonts. 


Returns the logical extents of an 8-bit 
character string by querying the server. 


Returns logical extents of an 16-bit character 
string by querying the server. 


Returns logical extents of an 8-bit character 
string. 

Returns logical extents of an 16-bit character 
string. 

Returns the length of a string composed of 
8-bit characters, given the string and the font 
in which the string is to be written. 


Returns the length of a string composed of 
16-bit characters, given the string and the font 
in which the string is to be written. 


7.1 


7.1.1 
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Drawing Text 


DRAW TEXT and DRAW TEXT 16 output arrays of text defined in text 
item structures. Each binding includes a text item structure for 8-bit 
strings and a text item structure for 16-bit strings. The following sections 
describe these structures for each binding. 


Text Item 8-Bit Data Structure 


The data structure for the VAX binding is shown in Figure 7-1, and 
information about members in the data structure is described in 
Table 7—2. 


Figure 7-1 Text Item Data Structure (VAX Binding) 












; 
x$l_text_n_chars 4 

x$l_text_delta 8 

x$l_text_font 12 

Table 7-2 Members of the Text Item Data Structure (VAX Binding) 

Member Name Contents 

X$A_TEXT_CHARS Address of a string of characters. 

X$L_TEXT_N_CHARS Number of characters in the string. 

X$L_TEXT_DELTA Spacing before the start of the string. Spacing is always 
added to the string origin and is not dependent on the 
font used. 

X$L_TEXT_FONT Identifier of the font used to print the string. If the value 


of this member is x$c_none, the server uses the current 
font in the GC data structure. If the member has a value 
other than x$c_none, the specified font is stored in the 
GC data structure. 


The data structure for the MIT C binding is shown in Figure 7-2, 
and information about members in the data structure is described in 
Table 7-3. 
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Figure 7-2 Text Item Data Structure (MIT C Binding) 


typedef struct { 
char *chars; 
int nchars; 
int delta; 
Font font; 

} XTextItem; 


Table 7-3. Members of the Text Item Data Structure (MIT C Binding) 


Member Name Contents 


chars The address of a string of characters. 

nchars Number of characters in the string. 

delta Spacing before the start of the string. Spacing is always added to 
the string origin and is not dependent on the font used. 

font Identifier of the font used to print the string. If the value of this 


member is None, the server uses the current font in the GC 
data structure. If the member has a value other than None, the 
specified font is stored in the GC data structure. 


Text Item 16-Bit Data Structure 


The data structure for the VAX binding is shown in Figure 7-3, and 
information about members in the data structure is described in 
Table 7~4. 


Figure 7-3 Text Item 16 Data Structure (VAX Binding) 







Table 7-4 Members of the Text Item 16 Data Structure (VAX Binding) 









Member Name Contents 
X$A_TX16_CHARS Address of a string of characters stored in a char 2b data 
structure. 


(continued on next page) 
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Table 7-4 (Cont.) Members of the Text Item 16 Data Structure (VAX 


Binding) 

Member Name Contents 

X$L_TX16_N_ CHARS Number of characters in the string. 

X$L_TX16_DELTA Spacing before the start of the string. Spacing is always 
added to the string origin and is not dependent on the 
font used. 

X$L_TX16_FONT Identifier of the font used to print the string. If the value 


of this member is x$c_none, the server uses the current 
font in the GC data structure. If the member has a value 
other than x$c_none, the specified font is stored in the 
GC data structure. 


The data structure for the MIT C binding is shown in Figure 7-4, 
and information about members in the data structure is described in 
Table 7-5. 


Figure 7-4 Text Item 16 Data Structure (MIT C Binding) 


typedef struct { 
XChar2b *chars; 
int nchars; 
int delta; 
Font font; 

} XTextIteml16; 


Table 7-5 Members of the Text Item 16 Data Structure (MIT C Binding) 


Member Name Contents 


chars The address of a string of characters stored in a char 2b data 
structure. For a description of the char 2b data structure, see the 
description immediately following this table. 


nchars Number of characters in the string. 

delta Spacing before the start of the string. Spacing is always added to 
the string origin and is not dependent on the font used. 

font Identifier of the font used to print the string. If the value of this 


member is None, the server uses the current font in the GC 
data structure. If the member has a value other than None, the 
specified font is stored in the GC data structure. 





7.2 Text Routines 
The following pages describe the Xlib text routines. 
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DRAW IMAGE STRING 


Draws a string of 8-bit character image text to the screen. 





VAX FORMAT X$DRAW_IMAGE_ STRING 
(display, drawable_id, gc_id, x_coord, y_coord, string) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
string char_string character string read descriptor 





MITC FORMAT XDrawlmageString 
(display, drawable_id, gc_id, x_coord, y_coord, string, 
length) 


argument 
information XDrawlmageString (display, drawable_id, gc_id, x_coord, 
y_coord, string, length) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x coord, y_ coord; 
char *string; 
int length; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) in which you want to 
write the text. This identifier is returned when you create the drawable. 


gc_id 

The identifier of the graphics context to be used for writing the text. 
This identifier is returned when you create a graphics context using the 
CREATE GC routine. 
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For image text to be visible, the foreground and background values in the 
graphics context must be different. Otherwise, you get a filled rectangle 
which may or may not show up, depending on the current window 
background color. This is not true, however, if the text string extends 
outside the background rectangle on the left or right. 


x_coord 


The x-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


y_coord 


The y-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


string 
The text string to be written to the screen. 


VAX only 


The string argument is the address of a descriptor that points to a string. 


length (MIT C only) 


The length of the string. A null character can be a valid representation, so 
null termination cannot be used to determine the length of the string. 





DESCRIPTION 
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DRAW IMAGE STRING draws a string of 8-bit character image text to 
the screen. Image text is drawn by painting both the foreground and 
background pixels of each character, using a single font. 


First, a destination rectangle is drawn using the specified background 
color defined in graphics context. The upper left corner of the rectangle is 
point (x, y), defined as follows: 


¢ x= The x-coordinate of the baseline starting point. 


© y= The y-coordinate of the baseline starting point minus the font 
ascent. (Font ascent is measured from top to bottom.) 


The width of the destination rectangle is the overall width of all characters 
in the string (the sum of all the widths). 


The height of the rectangle is the sum of the font ascent and the font 
descent. 


Leftbearing, rightbearing, font ascent, and font descent values are 
returned by QUERY TEXT EXTENTS. 


After the destination rectangle is drawn, text is drawn using the specified 
foreground color. 


DRAW IMAGE STRING uses the following graphics context members: 
e Plane mask 

* Foreground 

¢ Background 

¢ Font 


e Subwindow mode 


* Clip x origin 
¢ Clip y origin 
¢ Clip mask 
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For more information about graphics context members, see Chapter 5. 


This routine disregards any function or fill style specified in the graphics 
context. DRAW IMAGE STRING always uses GXcopy as the function and 


solid as the fill style. 





X ERRORS 


VAX 


X$C_BAD_DRAWABLE BadDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are: 


. 


In a graphics request, the root and 
depth of the graphics context does 
not match that of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 
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DRAW IMAGE STRING 16 


Draws a string of 16-bit character image text to the screen. 





VAXFORMAT X$DRAW_IMAGE STRING_16 
(display, drawable_id, gc_id, x_coord, y_coord, 


string16, length) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
string16 array word read reference 
length word uns word read reference 





MITC FORMAT XDrawlmageString16 
(display, drawable_id, gc_id, x_coord, y_coord, 
string 16, length) 


argument 
information XDrawImageString16(display, drawable_id, gc_id, x_coord, y_coord, 
stringl6, length) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x_coord, y_coord; 
XChar2b *stringl16; 
int length; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 
The identifier of the window or pixmap (drawable) in which you want to 
write the text. This identifier is returned when you create the drawable. 
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gc_id 

The identifier of the graphics context to be used for writing the text. 
This identifier is returned when you create a graphics context using the 
CREATE GC routine. 


For image text to be visible, the foreground and background values in the 
graphics context must be different. Otherwise, you get a filled rectangle 
which may or may not show up, depending on the current window 
background color. This is not true, however, if the text string extends 
outside the background rectangle on the left or right. 


xX_coord 
The x-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


y_coord 


The y-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


string16 


The text string to be written to the screen. 


length 
The length of the string. A null character may be a valid representation, 
so null termination cannot be used to determine the length of the string. 





DESCRIPTION 


DRAW IMAGE STRING 16 draws a string of 16-bit character image text 
to the screen. Image text is drawn by painting both the foreground and 
background pixels of each character, using a single font. 


First, a destination rectangle is drawn using the specified background 
color defined in graphics context. The upper left corner of the rectangle is 
point (x,y), defined as follows: 


* x= The x-coordinate of the baseline starting point. 


* y= The y-coordinate of the baseline starting point minus the font 
ascent. (Font ascent is measured from top to bottom.) 


The width of the destination rectangle is the overall width of all characters 
in the string. 


The height of the rectangle is the sum of the font ascent and the font 
descent. 


Leftbearing, rightbearing, font ascent, and font descent values are 
returned by QUERY TEXT EXTENTS 16. 


After the destination rectangle is drawn, text is drawn using the specified 
foreground color. 


DRAW IMAGE STRING 16 uses the following graphics context members: 
¢ Plane mask 
¢ Foreground 
¢ Background 
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¢ Font 

¢ Subwindow mode 
* Clip x origin 

¢ Clip y origin 

¢ Clip mask 


For more information about graphics context members, see Chapter 5. 


This routine disregards any function or fill style specified in the graphics 
context. DRAW IMAGE STRING always uses GXcopy as the function and 


solid as the fill style. 





X ERRORS 
VAX 


X$C_BAD_DRAWABLE BadDrawable 


X$C_BAD_GC 


X$C_BAD_MATCH 
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Cc 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 

A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are: 


in a graphics request, the root and 
depth of the graphics context does 
not match that of the drawable. 

An input-only window is used as a 
drawable. 

One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

An input-only window lacks this 
attribute. 


Text Routines 
DRAW STRING 


DRAW STRING 


Draws a text string (8-bit characters) to the screen in a single font, drawing 
only foreground pixels. 





VAX FORMAT X$DRAW_STRING 
(display, drawable_id, gc_id, x_coord, y_coord, string) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
string char_string character string read descriptor 





MITC FORMAT XDrawString 
(display, drawable_id, gc_id, x_coord, y_coord, string, 
length) 


argument 
information XDrawString(display, drawable_id, gc_id, x_coord, y_ coord, 
string, length) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x_coord, y_ coord; 
char *string; 
int length; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the drawable in which you want to write the text. The 
drawable can be either a window or a pixmap. This identifier is returned 
when you create the drawable. 


gc_id 

The identifier of the graphics context to be used for writing the text. 
This identifier is returned when you create a graphics context using the 
CREATE GC routine. 
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Text Routines 
DRAW STRING 


x_coord 
The x-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


y_coord 
The y-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


string 


A null-terminated string to be written to the screen. 
length (MIT C only) 
The length of the string specified. 


Because a null character can be a valid representation, null termination 
cannot be used to determine the length of the string. 





DESCRIPTION 
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DRAW STRING writes 8-bit character text to the screen using the font 
specified in the graphics context, drawing only foreground pixels. 


DRAW STRING uses the following graphics context members to control 
the appearance of the text on the screen: 


¢ Function 

¢ Plane mask 

e Fill style 

° Font 

* Subwindow mode 
° Clip x origin 

¢ Clip y origin 

¢ Clip mask 


Each character image defined by the font member of graphics context is 
treated as an additional mask for a fill operation on the drawable. 


DRAW STRING also uses the following graphics context mode-dependent 
members: 


¢ Foreground 


¢ Background 


e §6Tile 

¢ Stipple 

* Ts x origin 
e Ts y origin 


For more information on graphics context, see the Chapter 5. 


Text Routines 
DRAW STRING 





X ERRORS 


VAX Cc 
X$C_BAD_DRAWABLE _ BadDrawable 


X$C_BAD_FONT BadFont 
X$C_BAD_GC BadGC 
X$C_BAD_MATCH BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a font 
argument does not name a defined font 
(or, in some cases, graphics context). 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are: 


« In a graphics request, the root and 
depth of the graphics context does 
not match that of the drawable. 

« An input-only window is used as a 
drawable. 

« One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

* — An input-only window lacks this 
attribute. 
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Text Routines 
DRAW STRING 16 


DRAW STRING 16 


Draws a text string (16-bit characters) to the screen in a single font, using only 
foreground pixels. 





VAX FORMAT X$DRAW_STRING_16 
(display, drawable_id, gc_id, x_coord, y_coord, 


string16, length) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
string16 array word read reference 
length word word read reference 





MITC FORMAT XDrawString16 
(display, drawable_id, gc_id, x_coord, y_coord, 
string 16, length) 


argument 
information XDrawStringl6(display, drawable_id, gc_id, x_coord, y_coord, 
stringl6, length) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x_coord, y coord; 
XChar2b *stringl6; 
int length; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the drawable in which you want to write the text. The 
drawable can be either a window or a pixmap. This identifier is returned 
when you create the drawable. 
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Text Routines 
DRAW STRING 16 


ge_id 

The identifier of the graphics context to be used for writing the text. 
This identifier is returned when you create a graphics context using the 
CREATE GC routine. 


x_coord 
The x-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


y_coord 


The y-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


string16 


A null-terminated string to be written to the screen. 
length 
The length of the string specified. 


Because a null character can be a valid representation, null termination 
cannot be used to determine the length of the string. 





DESCRIPTION 


DRAW STRING 16 writes 16-bit character text to the screen using the font 
specified in the graphics context, drawing only foreground pixels. 


DRAW STRING 16 uses the following graphics context members to control 
the appearance of the text on the screen: 


¢ Function 

* Plane mask 

¢ Fill style 

¢ =6Font 

¢ Subwindow mode 

¢ Clip x origin 

° Clip y origin 

* Clip mask 

Each character image defined by the font member of graphics context is 
treated as an additional mask for a fill operation on the drawable. 


DRAW STRING 16 also uses the following graphics context mode- 
dependent members: 


¢ Foreground 
¢ Background 
¢ Tile 
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DRAW STRING 16 


* Stipple 
e §6Ts x origin 


e Ts y origin 


For more information about graphics context, see Chapter 5. 





X ERRORS 
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VAX 


X$C_BAD_DRAWABLE _ BadDrawable 


X$C_BAD_FONT 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 


BadFont 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined 
window or pixmap. 


A value that you specified for a font 
argument does not name a defined font 
(or, in some cases, graphics context). 


A value that you specified for a graphics 
context argument does not name a 
defined graphics context. 


Possible causes are: 


* Ina graphics request, the root and 
depth of the graphics context does 
not match that of the drawable. 

* — An input-only window is used as a 
drawable. 

* One argument or pair of arguments 
has the correct type and range but 
fails to match in some other way 
required by the request. 

¢ — An input-only window lacks this 
attribute. 


Text Routines 
DRAW TEXT 


DRAW TEXT 


Draws text (8-bit characters) to the screen in various fonts. 





VAX FORMAT X$DRAW_TEXT 
(display, drawable_id, gc_id, x_coord, y_coord, items, 


num_items) 

argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
items array vector_longword read reference 
num_items longword longword read reference 





MITC FORMAT XDrawText 
(display, drawable_id, gc_id, x_coord, y_coord, items, 
num_items) 


argument 
information XDrawText (display, drawable_id, gc_id, x_coord, y_ coord, items, 
num_items) 
Display *display; 
Drawable drawable id; 
GC gc_id; 
int x_coord, y_ coord; 
XTextItem *items; 
int num_items; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the drawable in which you want to write the text. The 
drawable can be either a window or a pixmap. This identifier is returned 
when you create the drawable. 
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gc_id 
The identifier of the graphics context to be used for writing the text. 


This identifier is returned when you create a graphics context using the 
CREATE GC routine. 


X_coord 


The x-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


y_coord 


The y-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


items 


An array of text item structures. The number of text item structures in 
the array is specified by num_items. 


num_items 
The number of items (elements) in the specified text item array. 





DESCRIPTION 
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DRAW TEXT writes 8-bit character text to the screen using one or more 
onts. The text is defined in an array of text item structures. Each text 
item structure contains the following information: 


e¢ Pointer to the text string 
¢ Number of characters in the string 


¢ Change in horizontal x position of the text before it is mapped to the 
drawable 


Change in text position is relative to the end of the last string. The 
end of the last string is calculated as the starting position on the last 


string, plus the sum of the character widths for all characters in the 
string. 


¢ Identifier of the font to be used to draw the string 


For more information about the text item structure, see Section 7.1.1. 


Text items are specified in the array in the order in which the text is 
written. That is, if DRAW TEXT is used to write three words, one in 
10-point Times Roman, one in 12-point Times Roman, and one in 24-point 
Times Roman, the item array would have three elements, each describing 
the word and its respective font. 


DRAW TEXT uses the following graphics context members to control the 
appearance of the text on the screen: 


¢ Function 

* Plane mask 

¢ Fill style 

¢ Subwindow mode 


¢ Clip x origin 


¢ Clip y origin 
¢ Clip mask 


Text Routines 
DRAW TEXT 


If a font is not specified in the text item structure, the graphics context 
default font is used. 


Each character image defined by the font member of graphics context is 
treated as an additional mask for a fill operation on the drawable. 


DRAW TEXT also uses the following graphics context mode-dependent 


members: 

¢ Foreground 
¢ Background 
* Tile 

¢ Stipple 

¢ Ts x origin 


° Ts y origin 


For more information about graphics context, see Chapter 5. 





X ERRORS 


VAX 
X$C_BAD_ 


DRAWABLE 
X$C_BAD_FONT 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 
BadDrawable 


BadFont 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined window or 
pixmap. 

A value that you specified for a font argument 
does not name a defined font (or, in some 
cases, graphics context). 


A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


Possible causes are: 


¢ Ina graphics request, the root and depth 
of the graphics context does not match 
that of the drawable. 

« An input-only window is used as a 
drawable. 

*« One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by the 
request. 

¢ — An input-only window lacks this attribute. 
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Text Routines 
DRAW TEXT 16 


DRAW TEXT 16 


Draws text (16-bit characters) to the screen in various fonts. 





VAX FORMAT xX$DRAW_TEXT_16 
(display, drawable_id, gc_id, x_coord, y_coord, 
items16, num_items) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
drawable_id identifier uns longword read reference 
gc_id identifier uns longword read reference 
x_coord longword longword read reference 
y_coord longword longword read reference 
items16 array vector_longword read reference 
num_items longword longword read reference 





MITC FORMAT XDrawText16 
(display, drawable_id, gc_id, x_coord, y_coord, 
items16, num_items) 


argument 
information XDrawText16(display, drawable_id, gc_id, x_coord, y_coord, 
items16, num_items) 
Display *display; 
Drawable drawable_id; 
GC gc_id; 
int x_coord, y_ coord; 
XTextIteml6 *items16; 
int num_items; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


drawable_id 

The identifier of the drawable in which you want to write the text. The 
drawable can be either a window or a pixmap. This identifier is returned 
when you create the drawable. 
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DRAW TEXT 16 


gc_id 

The identifier of the graphics context to be used for writing the text. 
This identifier is returned when you create a graphics context using the 
CREATE GC routine. 


x_coord 
The x-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


y_coord 
The y-coordinate of the starting point of the text baseline. Coordinates are 
specified in pixels relative to the origin of the drawable. 


items16 


An array of text item 16 structures. The number of text item 16 structures 
in the array is specified by num_items. 


num_items 
The number of items (elements) in the specified text item array. 





DESCRIPTION 


DRAW TEXT 16 writes 16-bit character text to the screen using one or 
more fonts. The text is defined in an array of text item 16 structures. 
Each text item 16 structure contains the following information: 


¢ Pointer to the text string 
¢ Number of characters in the string 


¢ Change in horizontal x position of the text before it is mapped to the 
drawable 


Change in text position is relative to the end of the last string. The 
end of the last string is calculated as the starting position on the last 
string, plus the sum of the character widths for all characters in the 
string. 


¢ Identifier of the font to be used to draw the string 


For more information about the text item 16 structure, see Section 7.1.2. 


Text items are specified in the array in the order in which the text is 
written. That is, if DRAW TEXT 16 is used to write three words, one in 
10-point Times Roman, one in 12-point Times Roman, and one in 24-point 
Times Roman, the item array would have three elements, each describing 
the word and its respective font. 


DRAW TEXT 16 uses the following graphics context members to control 
the appearance of the text on the screen: 


¢ Function 

¢ Plane mask 

¢ ©6Fill style 

¢ Subwindow mode 


¢ Clip x origin 
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¢ Clip y origin 
¢ Clip mask 


If a font is not specified in the text item 16 structure, the graphics context 
default font is used. 


Each character image defined by the font member of graphics context is 
treated as an additional mask for a fill operation on the drawable. 


DRAW TEXT 16 also uses the following graphics context mode-dependent 


members: 

¢ Foreground 
¢ Background 
e Tile 

¢ Stipple 

¢ Ts x origin 


e Ts y origin 


For more information about graphics context, see Chapter 5. 





X ERRORS 
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VAX 
X$C_BAD_ 


DRAWABLE 
X$C_BAD_FONT 


X$C_BAD_GC 


X$C_BAD_MATCH 


Cc 
BadDrawable 


BadFont 


BadGC 


BadMatch 


Description 


A value that you specified for a drawable 
argument does not name a defined window or 
pixmap. 

A value that you specified for a font argument 
does not name a defined font (or, in some 
cases, graphics context). 


A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


‘ \ 
Possible causes are: 


* In a graphics request, the root and depth 
of the graphics context does not match 
that of the drawable. 

* An input-only window is used as a 
drawable. 

* One argument or pair of arguments has 
the correct type and range but fails to 
match in some other way required by the 
request. 

* — An input-only window lacks this attribute. 


Text Routines 
QUERY TEXT EXTENTS 


QUERY TEXT EXTENTS 


Returns the logical extents of an 8-bit character string by querying the server. 





VAX FORMAT X$QUERY_TEXT_EXTENTS 
(display, font_id, string [,direction_return] 
[,ascent_return] [,descent_return] [,overall_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
font_id identifier uns longword read reference 
string char_string character string read descriptor 
direction_return — longword longword write reference 
ascent_return longword longword write reference 
descent_return longword longword write reference 
overall_return record x$char_struct write reference 





MITC FORMAT XQueryTextExtents 
(display, font_id, string, num_chars, direction_return, 
ascent_return, descent_return, overall_return) 


argument 
information XQueryTextExtents (display, font_id, string, num_chars, 
direction_return, ascent_return, 
descent_return, overall_ return) 
Display *display; 
XID font_id; 
char *string; 
int num_chars; 
int *direction_return; 
int *ascent_return, *descent_return; 
XCharStruct *overall_return; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 


font_id 

The identifier of the font whose extents are being queried. The font 
identifier is returned by LOAD FONT. The address of the font data 
structure, which includes the font identifier, is returned by LOAD QUERY 
FONT. 
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QUERY TEXT EXTENTS 


string 


The character string whose logical extents are being queried. 


num_chars (MIT C only) 


The number of characters in the string whose extents are being queried. 


direction_return 

The direction the string is painted on the screen. The direction_return 
argument is the returned value of the direction element of the font data 
structure. 


VAX only 
This argument is optional. 


ascent_return 

The maximum ascent of the font used to draw the string. The 
ascent_return argument is the returned value of the font ascent element 
of the font data structure. 


VAX only 


This argument is optional. 


descent_return 

The maximum descent of the font used to draw the string. The 
descent_return argument is the returned value of the font descent 
element of the font data structure. 


VAX only 


This argument is optional. 


overall_return 
The minimum left bearing, maximum right bearing, string width, 
maximum character ascent, and maximum character descent. 


Values are returned from a character structure. 


For information about the character structure, see Chapter 13. 


VAX only 


This argument is optional. 





DESCRIPTION 
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QUERY TEXT EXTENTS returns the logical extents of a specified 8-bit 
string. Unlike TEXT EXTENTS, which determines the sizes of characters 
directly from the font data structure, QUERY TEXT EXTENTS computes 
the size of the string by querying the server. Because this requires extra 
overhead, use QUERY TEXT EXTENTS only when LOAD FONT has 
loaded the font used to write the string specified by string. 


Given an 8-bit string, QUERY TEXT EXTENTS returns the following 
information about the extents: 


¢ Direction the font is painted 


e Ascent above the baseline used for determining line spacing 


Text Routines 
QUERY TEXT EXTENTS 


* Descent below the baseline used for determining line spacing 


e Character extents 


The following string extents are returned: 


Extent Value 

Leftbearing The minimum left bearing of all characters in the string 
Rightbearing The maximum right bearing of all characters in the string 
Width The sum of all character widths in the string 

Ascent The maximum ascent of all characters in the string 
Descent The maximum descent of all characters in the string 


When a font has no defined default character, undefined characters in the 
specified string are given zero character metric values. 





X ERRORS QUERY TEXT EXTENTS generates the following errors: 
VAX Cc Description 
X$C_BAD_FONT  BadFont A value that you specified for a font argument 


does not name a defined font (or, in some 
cases, graphics context). 

X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 
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QUERY TEXT EXTENTS 16 


Returns logical extents of a 16-bit character string by querying the server. 





VAX FORMAT X$QUERY_TEXT_EXTENTS_16 
(display, font_id, string16, num_chars 
[,direction_return] [,ascent_return] [,descent_return] 
[,overall_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
display identifier uns longword read reference 
font_id identifier uns longword read reference 
stringié6 array word read reference 
num_chars word word read reference 
direction_return — longword longword write reference 
ascent_return longword longword write reference 
descent_return longword longword write reference 
overall_return record x$char_struct read reference 





MITC FORMAT XQueryTextExtents16 
(display, font_id, string16, num_chars, 
direction_return, ascent_return, descent_return, 
overall_return) 


argument 
information XQueryTextExtents16 (display, font_id, stringl6, num_chars, 
direction_return, ascent_return, 
descent_return, overall_return) 
Display *display; 
XID font_id; 
XChar2b *stringl6; 
int num_chars; 
int *direction_return; 
int *ascent_return, *descent_return; 
XCharStruct *overall return; 





ARGUMENTS _ display 
The display information originally returned by OPEN DISPLAY. 
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font_id 

The identifier of the font whose extents you want to know. The font 
identifier is returned by LOAD FONT. The address of the font data 
structure, which includes the font identifier, is returned by LOAD QUERY 
FONT. 


string16 


The character string whose logical extents are being queried. 


num_chars 


The number of characters in the string whose extents are being queried. 


direction_return 

The direction the string is painted on the screen. The direction_return 
argument is the returned value of the direction element of the font data 
structure. 


VAX only 
This argument is optional. 


ascent_return 

Maximum ascent of the font used to draw the string. The ascent_return 
argument is the returned value of the font ascent element of the font data 
structure. 


VAX only 
This argument is optional. 


descent_return 

Maximum descent of the font used to draw the string. The 
descent_return argument is the returned value of the font descent 
element of the font data structure. 


VAX only 
This argument is optional. 


overall_return 
The minimum left bearing, maximum right bearing, string width, 
maximum character ascent, and maximum character descent. 


Values are returned from a character structure. 
For information about the structure, see Chapter 13. 
VAX only 


This argument is optional. 





DESCRIPTION 


QUERY TEXT EXTENTS 16 returns the logical extents of a specified 
16-bit string. Unlike TEXT EXTENTS 16, which determines the sizes of 
characters directly from the font data structure, QUERY TEXT EXTENTS 
16 computes the size of the string by querying the server. Because this 
results in additional overhead, use QUERY TEXT EXTENTS 16 only when 
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QUERY TEXT EXTENTS 16 


LOAD FONT has loaded the font used to write the string specified by 
string16. 


Given a 16-bit string, QUERY TEXT EXTENTS 16 returns the following 
information about the extents: 


¢ Direction the font is painted 
¢ Ascent above the baseline used for determining line spacing 
¢ Descent below the baseline used for determining line spacing 


¢ Character extents 


The following string extents are returned: 


Extent Value 

Leftbearing The minimum left bearing of all characters in the string 
Rightbearing The maximum right bearing of all characters in the string 
Width The sum of all character widths in the string 

Ascent The maximum ascent of all characters in the string 
Descent The maximum descent of all characters in the string 


When a font has no defined default character, undefined characters in the 
specified string are given zero character metric values. 





X ERRORS 
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VAX Cc Description 


X$C_BAD_FONT  BadFont A value that you specified for a font argument 
does not name a defined font (or, in some 
cases, graphics context). 


X$C_BAD_GC BadGC A value that you specified for a graphics 
context argument does not name a defined 
graphics context. 


Text Routines 
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TEXT EXTENTS 


Returns logical extents of an 8-bit character string in a given font. 





VAX FORMAT X$TEXT_EXTENTS 
(font_ptr, string [,direction_return] [,ascent_return] 
[,descent_return] [,overall_return]) 





argument 

information Argument Usage Data Type Access Mechanism 
font_ptr record x$font_struct read reference 
string char_string character string read descriptor 
direction_return longword longword write reference 
ascent_return longword longword write reference 
descent_return — longword longword write reference 
overall_return record x$char_struct write reference 





MITC FORMAT XTextExtents 
(font_ptr, string, num_chars, direction_return, 
ascent_return, descent_return, overall_return) 


argument 
information XTextExtents(font_ptr, string, num_chars, direction_return, 
ascent_return, descent_return, overall_return) 
XFontStruct *font_ptr; 
char *string; 
int num_chars; 
int *direction_return; 
int *ascent_return, *descent_return; 
XCharStruct *overall return; 





ARGUMENTS _ font_ptr 
The address of a font data structure. TEXT EXTENTS uses the character 
information contained in the font data structure to determine extents. The 
address of the font data structure is returned by LOAD QUERY FONT or 
QUERY FONT. 


string 
The character string whose logical extents are being queried. 


num_chars (MIT C only) 


The number of characters in the string whose extents are being queried. 


729 


Text Routines 
TEXT EXTENTS 


direction_return 

The direction the font is painted on the screen. The direction_return 
argument is the returned value of the direction element of the font data 
structure. 


VAX only 
This argument is optional. 


ascent_return 

The maximum ascent of the font that draws the string. The 
ascent_return argument is the returned value of the font ascent element 
of the font data structure. 


VAX only 


This argument is optional. 


descent_return 

Maximum descent of the font that draws the string. The descent_return 
argument is the returned value of the font descent element of the font data 
structure. 


VAX only 
This argument is optional. 


overall_return 
The minimum left bearing, maximum right bearing, string width, 
maximum character ascent, and maximum character descent. 


For more information about the character structure, see Chapter 13. 


VAX only 


This argument is optional. 





DESCRIPTION 
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TEXT EXTENTS returns the logical extents of a specified 8-bit string in 
a given font. Unlike QUERY TEXT EXTENTS, which queries the server 
for the sizes of characters in the string, TEXT EXTENTS uses the pointer 
returned by LOAD QUERY FONT to query the font data structure directly. 


Given an 8-bit string, TEXT EXTENTS returns the following information 
about the extents: 


¢ Direction the font is painted 
¢ Ascent above the baseline used for determining line spacing 
¢ Descent below the baseline used for determining line spacing 


e Character extents 


Text Routines 
TEXT EXTENTS 


The following string extents are returned: 


Extent Value 

Leftbearing The minimum left bearing of all characters in the string 
Rightbearing The maximum right bearing of all characters in the string 
Width The sum of all character widths in the string 

Ascent The maximum ascent of all characters in the string 
Descent The maximum descent of all characters in the string 


When a font has no defined default character, undefined characters in the 
specified string receive zero character metric values. 
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TEXT EXTENTS 16 


Returns logical extents of a 16-bit character string in a given font. 





VAX FORMAT X$TEXT_EXTENTS 16 
(font_ptr,string, num_chars [,direction_return] 
[,ascent_return] [, descent_return] [,overall_return]) 


argument 

information Argument Usage Data Type Access Mechanism 
font_ptr record x$font_struct read reference 
string array word read reference 
num_chars word word! read reference 
direction_return — longword longword write reference 
ascent_return longword longword write reference 
descent_return longword longword write reference 
overall_return record x$char_struct write reference 
Tunsigned 





MITC FORMAT XTextExtents16 
(font_ptr,string, num_chars, direction_return, 
ascent_return, descent_return, overall_return) 





argument 
information XTextExtents16(font_ptr, string, num_chars, direction_return, 
ascent_return, descent_return, overall_return) 
XFontStruct *font_ptr; 
XChar2b *string; 
int num_chars; 
int *direction_return; 
int *ascent_return, *descent_return; 
XCharStruct *overall_ return; 





ARGUMENTS _ font_pir 
The address of a font data structure. TEXT EXTENTS uses the character 
information contained in the font data structure to determine extents. The 
address of the font data structure is returned by LOAD QUERY FONT or 
QUERY FONT. 


string 
The character string whose logical extents are being queried. 
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num_chars 
The number of characters in the string whose extents are being queried. 


direction_return 

The direction the string is painted on the screen. The direction_return 
argument is the returned value of the direction element of the font data 
structure. 


VAX only 


This argument is optional. 


ascent_ return 

Maximum ascent of the font used to draw the string. The ascent_return 
argument is the returned value of the font ascent element of the font data 
structure. 


VAX only 


This argument is optional. 


descent_return 

Maximum descent of the font used to draw the string. The 
descent_return argument is the returned value of the font descent 
element of the font data structure. 


VAX only 
This argument is optional. 


overall_return 
The minimum left bearing, maximum right bearing, string width, 
maximum character ascent, and maximum character descent of the string. 


For more information about the character structure, see Chapter 13. 
VAX only 
This argument is optional. 





DESCRIPTION 


TEXT EXTENTS 16 returns the logical extents of a specified 16-bit string 
of a given font. Unlike QUERY TEXT EXTENTS 16, which queries the 
server for the sizes of characters in the string, TEXT EXTENTS 16 uses 
the pointer returned by LOAD QUERY FONT to query the font data 
structure directly. 


Given a 16-bit string, TEXT EXTENTS 16 returns the following 
information about extents: 


¢ Direction the font is painted 
¢ Ascent above the baseline used for determining line spacing 
* Descent below the baseline used for determining line spacing 


e Character extents 
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The following string extents are returned: 


Extent Value 

Leftbearing The minimum left bearing of all characters in the string 
Rightbearing The maximum right bearing of all characters in the string 
Width The sum of all character widths in the string 

Ascent The maximum ascent of all characters in the string 
Descent The maximum descent of all characters in the string 


When fonts are defined with linear indexing rather than 2-byte matrix 
indexing, the server interprets each 2-byte character as a 16-bit number 
with the first byte as most significant. 


When a font has no defined default character, undefined characters in the 
specified string receive zero character metric values. 
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TEXT WIDTH 


Returns the length of a string composed of 8-bit characters, given the string 
and the font in which the string is to be written. 





VAX FORMAT _ width_return = X$TEXT_WIDTH 
(font_ptr, string) 


argument 

information Argument Usage Data Type Access Mechanism 
width_return longword uns longword write value 
font_ptr record x$font_struct read reference 
string char_string character string read descriptor 





MITC FORMAT width_return = XTextWidth 
(font_ptr, string, count) 





argument 

information int XTextWidth(font_ptr, string, count) 
XFontStruct *font_ptr; 
char *string; 
int count; 

RETURNS width_return 


The length, in pixels, of the specified string, measured using the character 
information stored in the specified font. 





ARGUMENTS _ font_pir 
The address of a font data structure. TEXT WIDTH uses the character 
information contained in the structure to calculate the length. The address 
of the structure is returned by LOAD QUERY FONT and QUERY FONT. 


string 


The character string to be measured for length. The string must consist of 
8-bit characters. 


count (MIT C only) 


The character count of the named string. 
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DESCRIPTION TEXT WIDTH returns the length of the specified string. 


Length, measured in the direction of text painting, is the sum of all the 
characters in the string. 


This information is stored in a font structure associated with the font used 
initially to create the string. The identifier of the structure is returned 
by FONT or QUERY FONT. For more information about the font data 
structure, see Chapter 13. 


Typically, this routine is used to ensure that a proposed character string 
does not exceed some maximum size, as when you are putting a label in a 
box on the screen. 
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TEXT WIDTH 16 


Returns the length of a string composed of 16-bit characters, given the string 
and the font in which the string is to be written. 





VAX FORMAT ~ width_return = X$TEXT_WIDTH_16 
(font_ptr, string16, count) 


argument 

information Argument Usage Data Type Access Mechanism 
width_return longword uns longword write value 
font_ptr record x$font_struct read reference 
string16 array word read reference 
count word uns word read reference 





MITC FORMAT width_return = XTextWidth16 
(font_ptr, string16, count) 





argument 

information int XTextWidth16(font_ptr, stringl6, count) 
XFontStruct *font_ptr; 
XChar2b *stringl6; 
int count; 

RETURNS width_return 


The length, in pixels, of the specified string, measured using the character 
information stored in the specified font. 





ARGUMENTS _font_pir 
The address of a font data structure. TEXT WIDTH 16 uses the character 
information contained in the font data structure to calculate the length. 
The address of the font data structure is returned by LOAD QUERY 
FONT and QUERY FONT. 


string16 
The character string to be measured for length. The string must consist of 
16-bit characters. 


count 
The character count of the named string. 
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DESCRIPTION TEXT WIDTH 16 returns the length of the specified string. 


Length, measured in the direction of text painting, is the sum of the width 
of all the characters in the string. 


This information is stored in a font structure associated with the font used 
initially to create the string. The identifier of the structure is returned 
by FONT or QUERY FONT. For more information about the font data 
structure, see Chapter 13. 


Typically, this routine is used to ensure that a proposed character string 
does not exceed some maximum size. 


